", …]}` and appends those properties to the type. The response is `201` with a
+`properties` array.
+
+- Only properties belonging to the **same project** can be attached. An id from another project is a
+ `400 validation_error` that names the offending ids, never a silent skip — one bad id rejects the whole call.
+- Re-attaching a property the type already exposes is harmless. The call still returns `201` and the type is not left
+ with a duplicate, so a replayed request is safe.
+
+## Detaching
+
+`DELETE .../properties/{pk}/` removes the link and returns `204`.
+
+::: warning Detaching clears stored values
+The property definition survives — it stays in the project and stays attached to every other type that uses it, ready
+to re-attach. What does not survive is the data: the values already recorded for that property on work items **of this
+type** are removed with the link, and re-attaching does not bring them back.
+
+Deleting the definition outright is a different call —
+[Delete a work item property](/api-reference/v2/work-item-properties/delete-work-item-property).
+:::
+
+## Mode matters for writes, not reads
+
+Attaching and detaching are **project-mode** writes. If the workspace manages work item types at the workspace level,
+both return `409 work_item_types_managed_at_workspace` — the capability exists, it just lives on the other surface. Use
+[Attach a property to a workspace type](/api-reference/v2/workspace-work-item-type-properties/attach-workspace-type-property)
+instead.
+
+Reads are unaffected: listing and retrieving a type's properties works in either mode.
+
+See [Work item type modes](/api-reference/v2/work-item-type-modes) for how to tell which mode a workspace is in.
+
+## Changed from v1
+
+- In v1 a property was created **inside** a type, at
+ `POST /api/v1/workspaces/{slug}/projects/{project_id}/work-item-types/{type_id}/work-item-properties/`, so it belonged
+ to that one type.
+- In v2 the definition moved up to the project (`/work-item-properties/`) and this path became a link:
+ `POST` attaches existing properties, `DELETE` detaches one. There is no create and no update here.
+- One property can now be attached to several types.
+
+See [Migrating from v1](/api-reference/v2/migrating-from-v1) for the full list.
diff --git a/docs/api-reference/v2/work-item-types/create-work-item-type.md b/docs/api-reference/v2/work-item-types/create-work-item-type.md
new file mode 100644
index 00000000..712595c8
--- /dev/null
+++ b/docs/api-reference/v2/work-item-types/create-work-item-type.md
@@ -0,0 +1,220 @@
+---
+title: Create a work item type
+description: Create a project-level work item type in Plane with the v2 REST API. Body parameters, project mode requirements, OAuth scopes, error codes, and code examples.
+keywords: plane api v2, create work item type, issue type, project mode, external_id, POST work item types
+---
+
+# 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](/api-reference/v2/work-item-types/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.
+
+::: warning 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](/api-reference/v2/workspace-work-item-types/create-workspace-work-item-type) instead, then [import it into the project](/api-reference/v2/work-item-types/import-work-item-types). See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to add the type to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name for the type, for example `Bug`. Maximum 255 characters.
+
+
+
+
+
+What this type is for. This is not decoration: it is returned as `type_description` by the [schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema), which is how an integration or agent decides between `Bug` and `Task` without a human in the loop.
+
+
+
+
+
+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.
+
+
+
+
+
+Your system's identifier for this type, for sync and import correlation. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters, nullable.
+
+
+
+
+
+
+::: info is_default, is_epic, level and logo_props are not accepted here
+`is_default` moves through [mark-default](/api-reference/v2/work-item-types/mark-default-work-item-type). `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. |
+
+
+
+
+
+
+
+
+
+
+```bash
+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
+}'
+```
+
+
+
+
+```python
+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())
+```
+
+
+
+
+```javascript
+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();
+```
+
+
+
+
+
+
+```json
+{
+ "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"
+}
+```
+
+
+
+
+
+```json
+{
+ "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."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/
+
+
+
+
+
+Remove a work item type from a project. A successful delete returns `204` with an empty body.
+
+Deletion is guarded. A type that is the project default, or that still has work items on it, is rejected with `409 conflict` rather than cascading — the API will not silently untype existing work.
+
+If your goal is to stop people picking a type, [set `is_active` to `false`](/api-reference/v2/work-item-types/update-work-item-type) instead. That works regardless of how many work items already use the type, and it is reversible.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. Delete the type on [the workspace surface](/api-reference/v2/workspace-work-item-types/delete-workspace-work-item-type) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to delete.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------------------------- | ------------------------------------------------------------------------------ |
+| `400` | `validation_error` | The request could not be processed as sent. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't delete work item types. |
+| `404` | `resource_not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `409` | `work_item_types_managed_at_workspace` | The workspace manages types at the workspace level. Use the workspace surface. |
+| `409` | `conflict` | The type is the project default, or work items still use it. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+(empty body)
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/conflict",
+ "title": "Conflict",
+ "status": 409,
+ "code": "conflict",
+ "detail": "A work item type with existing work items cannot be deleted."
+}
+```
+
+
+
+
+
+ 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. That returned `id` is the type new work items land on when no `type_id` is supplied, and it is a valid target for [attaching properties](/api-reference/v2/work-item-type-properties/attach-type-property) straight away.
+
+There is **no request body**. The path carries everything the call needs.
+
+::: warning 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](/api-reference/v2/work-item-types/import-work-item-types) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to turn work item types on for.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. Send the request without a body.
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------------------------- | ------------------------------------------------------------------------------- |
+| `400` | `validation_error` | The request could not be processed as sent. |
+| `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_workspace` | The workspace manages types at the workspace level. Import instead of enabling. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+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"
+```
+
+
+
+
+```python
+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"])
+```
+
+
+
+
+```javascript
+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();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "name": "Task",
+ "description": "Default work item type with the option to add new properties",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "Check",
+ "background_color": "#1FA191"
+ }
+ },
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "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."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/schema/
+
+
+
+
+
+Ask the API what a work item of this type accepts. The response describes the **standard fields** every work item has — with the project's actual states, priorities, and estimate points inlined as valid options — plus the **custom properties** attached to this type, including which ones are required and what values they allow.
+
+This is the discovery endpoint. A client that is about to create a work item calls this first, then builds its request body from the answer instead of hardcoding a field list. That matters most for two callers:
+
+- **Integrations**, which must adapt when an admin adds a required property to a type. Reading the schema each time means a new required field surfaces as a field to fill, not as a `400` in production.
+- **AI agents and generated tooling**, which need a machine-readable contract. `fields` and `custom_fields` are shaped to be handed straight to a function-calling schema: every entry carries a type, a required flag, and its allowed options.
+
+Reads are unaffected by [work item type mode](/api-reference/v2/work-item-type-modes) — the schema resolves the type's properties whether they are owned by the project or by the workspace.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to. The schema is project-specific: states, labels, members, and estimate points all come from this project.
+
+
+
+
+
+The id of the work item type whose schema you want.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Comma-separated extra option lists to inline. Two values are recognized:
+
+- `members` — inlines the project's active members as the options for `assignee_ids`, and for any custom property that is a user relation
+- `labels` — inlines the project's labels as the options for `label_ids`
+
+Omit it and those fields still appear, they just describe themselves without an option list. These lists can be large in a big workspace, so ask for them only when you are actually rendering a picker — for example `?include=members,labels`.
+
+
+
+
+
+
+
+
+### Response Fields
+
+
+
+
+
+The type this schema describes. Send it as `type_id` on the work item you create. Nullable.
+
+
+
+
+
+The type's display name, for example `Bug`. Nullable.
+
+
+
+
+
+The type's description. This is the text a human or an agent reads to decide whether this is the right type for the work at hand, which is why filling it in on [create](/api-reference/v2/work-item-types/create-work-item-type) is worth the effort. Nullable.
+
+
+
+
+
+The icon and background color rendered next to the type. Nullable.
+
+
+
+
+
+The standard work item fields, keyed by the body parameter name you would send — `name`, `description_html`, `priority`, `state_id`, `assignee_ids`, `label_ids`, `start_date`, `target_date`, `parent_id`. Each entry carries a `type`, a `required` flag, and where it applies an `is_multi` flag, a `default`, a `max_length`, a `format`, or an `options` array.
+
+`state_id` and `priority` always arrive with their options inlined, because those are the two fields a client cannot guess. `estimate_point_id` appears only when the project has an estimate system configured.
+
+
+
+
+
+The custom properties attached to this type, keyed by property name. Each entry carries the property `id`, its `type`, `name`, `display_name`, `description`, a `required` flag, and an `is_multi` flag.
+
+- `OPTION` properties also carry an `options` array of `{ id, name, logo_props }`, narrowed to the options this type allows.
+- `RELATION` properties also carry a `relation_type`.
+
+Empty when the type has no properties attached, or when custom properties are not available for the workspace.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ----------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this project's work item types. |
+| `404` | `resource_not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/schema/?include=members,labels" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/schema/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"include": "members,labels"},
+)
+schema = response.json()
+
+required = [name for name, field in schema["custom_fields"].items() if field["required"]]
+print(schema["type_name"], "requires:", required)
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ include: "members,labels" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/schema/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const schema = await response.json();
+
+const required = Object.entries(schema.custom_fields)
+ .filter(([, field]) => field.required)
+ .map(([name]) => name);
+```
+
+
+
+
+
+
+```json
+{
+ "type_id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "type_name": "Bug",
+ "type_description": "Something is broken and needs a fix",
+ "type_logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "fields": {
+ "name": {
+ "type": "string",
+ "required": true,
+ "max_length": 255
+ },
+ "description_html": {
+ "type": "string",
+ "required": false
+ },
+ "priority": {
+ "type": "option",
+ "required": false,
+ "default": "none",
+ "options": [
+ { "value": "urgent", "label": "Urgent" },
+ { "value": "high", "label": "High" },
+ { "value": "medium", "label": "Medium" },
+ { "value": "low", "label": "Low" },
+ { "value": "none", "label": "None" }
+ ]
+ },
+ "state_id": {
+ "type": "uuid",
+ "required": false,
+ "options": [
+ {
+ "id": "2c4d16f8-9b3e-4a52-8d71-1f0e6c9a5b48",
+ "name": "Backlog",
+ "color": "#8b8d98",
+ "group": "backlog"
+ },
+ {
+ "id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "name": "In Progress",
+ "color": "#3f76ff",
+ "group": "started"
+ },
+ {
+ "id": "7b1e9d40-3c86-4f2a-9a5d-8e2b0c47d613",
+ "name": "Done",
+ "color": "#26a05f",
+ "group": "completed"
+ }
+ ]
+ },
+ "assignee_ids": {
+ "type": "uuid",
+ "is_multi": true,
+ "required": false,
+ "options": [
+ {
+ "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "display_name": "rin",
+ "email": "rin@my-team.dev"
+ }
+ ]
+ },
+ "label_ids": {
+ "type": "uuid",
+ "is_multi": true,
+ "required": false,
+ "options": [
+ {
+ "id": "5e0c7b93-1a24-4d68-8f31-9b7e2c05a4d7",
+ "name": "regression",
+ "color": "#f5a623"
+ }
+ ]
+ },
+ "start_date": {
+ "type": "date",
+ "required": false,
+ "format": "YYYY-MM-DD"
+ },
+ "target_date": {
+ "type": "date",
+ "required": false,
+ "format": "YYYY-MM-DD"
+ },
+ "parent_id": {
+ "type": "uuid",
+ "required": false
+ }
+ },
+ "custom_fields": {
+ "severity": {
+ "id": "a8b31d67-5e42-4c09-9f78-2d6b41e0c395",
+ "type": "OPTION",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly this breaks the product",
+ "required": true,
+ "is_multi": false,
+ "options": [
+ {
+ "id": "3f8c2a71-6d90-4e15-b243-0c9e7a5b16f8",
+ "name": "S1",
+ "logo_props": {}
+ },
+ {
+ "id": "b47e0d29-8153-4a6c-9e70-2f1d5c83a904",
+ "name": "S2",
+ "logo_props": {}
+ }
+ ]
+ },
+ "found_by": {
+ "id": "c0a95f38-7b1e-4d62-8305-6e4a9b27fd51",
+ "type": "RELATION",
+ "name": "found_by",
+ "display_name": "Found by",
+ "description": "",
+ "required": false,
+ "is_multi": false,
+ "relation_type": "USER",
+ "options": [
+ {
+ "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "display_name": "rin",
+ "email": "rin@my-team.dev"
+ }
+ ]
+ }
+ }
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/
+
+
+
+
+
+Retrieve one work item type by id. Use it to confirm a type still exists and is still active before you write a work item against it, or to refresh a cached name after someone renamed the type in the app.
+
+This returns the type's own attributes only. It does **not** tell you which fields or custom properties a work item of this type accepts — that is [Get a work item type schema](/api-reference/v2/work-item-types/get-work-item-type-schema).
+
+Reads work in either [work item type mode](/api-reference/v2/work-item-type-modes), so this call never needs to branch on how the workspace is configured.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to retrieve.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ----------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this project's work item types. |
+| `404` | `resource_not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "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"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource_not_found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "No work item type matches the given query."
+}
+```
+
+
+
+
+
+ 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](/api-reference/v2/workspace-work-item-types/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](/api-reference/v2/work-item-types/list-work-item-types) for the project and each one's [schema](/api-reference/v2/work-item-types/get-work-item-type-schema) resolves against this project's states, labels, and members.
+
+::: warning 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](/api-reference/v2/work-item-types/create-work-item-type) and there is nothing to import. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to import the types into.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+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. |
+
+
+
+
+
+
+
+
+
+
+```bash
+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"
+ ]
+}'
+```
+
+
+
+
+```python
+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
+```
+
+
+
+
+```javascript
+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
+```
+
+
+
+
+
+
+```text
+(empty body)
+```
+
+
+
+
+
+```json
+{
+ "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."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/
+
+
+
+
+
+Return the work item types available in a project as a paginated list. This is how you resolve a type name such as `Bug` to the `type_id` you send when creating a work item, and how you build a type picker that stays in sync with the project's configuration.
+
+Reading types is unaffected by [work item type mode](/api-reference/v2/work-item-type-modes). A project in workspace mode still lists the types imported into it here, so a read integration never has to branch on mode.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project whose work item types you want to list.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+Neither `order_by` nor `paginate` is validated — check your spelling, because both fail silently. An unrecognized `order_by` value falls back to the default ordering, and anything other than `paginate=cursor` uses offset pagination. A typo surfaces as an unexpected sort order or envelope, not as an error.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `level` , `-level` — the type hierarchy level
+- `name` , `-name` — alphabetical
+- `created_at` , `-created_at` — when each type was added
+- `id` , `-id`
+
+Order by `level` when you are rendering types to a user; it is the order the project itself uses.
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most projects define a handful of types, so one page is usually the whole set.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from the response.
+
+
+
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this project's work item types. |
+| `404` | `resource_not_found` | No such workspace or project, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/?order_by=level&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "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"},
+ params={"order_by": "level", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "level", per_page: "50" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "name": "Task",
+ "description": "Default work item type with the option to add new properties",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "Check",
+ "background_color": "#1FA191"
+ }
+ },
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "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"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 2,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "9c2f8e51-4a63-47d8-b1e0-5f7a2c40d693",
+ "name": "Task",
+ "description": "Default work item type with the option to add new properties",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "Check",
+ "background_color": "#1FA191"
+ }
+ },
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/mark-default/
+
+
+
+
+
+Promote a type to the project's default — the type new work items get when the request supplies no `type_id`.
+
+**Exactly one type per project is the default.** Marking a new one clears the flag on the type that held it, so promotion is a single request rather than a demote-then-promote pair. There is no way to have zero defaults, and no way to have two.
+
+There is **no request body**. The type is identified by `{pk}` in the path, and the response is the updated type.
+
+`is_default` is deliberately not writable through [create](/api-reference/v2/work-item-types/create-work-item-type) or [update](/api-reference/v2/work-item-types/update-work-item-type). Moving the flag has a side effect on another row, so it gets its own endpoint instead of hiding inside a `PATCH`.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. Promote the type on [the workspace surface](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to make the default.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. Send the request without a body.
+
+
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------------------------- | ------------------------------------------------------------------------------ |
+| `400` | `validation_error` | The request could not be processed as sent. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't update work item types. |
+| `404` | `resource_not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `409` | `work_item_types_managed_at_workspace` | The workspace manages types at the workspace level. Use the workspace surface. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/mark-default/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/mark-default/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json()["is_default"]) # True
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/mark-default/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {
+ "in_use": "icon",
+ "icon": {
+ "name": "AlertCircle",
+ "background_color": "#EF5974"
+ }
+ },
+ "created_at": "2026-01-14T09:24:03.117482Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "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."
+}
+```
+
+
+
+
+
+
+
+## The work item type object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the type. This is the value you send as `type_id` when creating a work item, and the `{type_id}` in the type-properties paths.
+
+- `name` _string_
+
+ Display name, for example `Bug`. Maximum 255 characters.
+
+- `description` _string_
+
+ Free-form explanation of when this type should be used. Worth filling in — an integration or agent reading the [schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema) sees this text as `type_description` and uses it to choose between types.
+
+- `is_active` _boolean_
+
+ Whether the type can be assigned to new work items. Deactivating a type hides it from pickers without deleting it or touching the work items that already use it.
+
+- `is_default` _boolean_
+
+ Whether new work items land on this type when no `type_id` is supplied. Exactly one type per project holds the flag. It is not writable through create or update — move it with [Mark a work item type as default](/api-reference/v2/work-item-types/mark-default-work-item-type).
+
+- `is_epic` _boolean_
+
+ Whether this is the project's epic type. Read-only — epics are provisioned by Plane, not authored through this endpoint.
+
+- `level` _number_
+
+ Hierarchy level for the type. Read-only, and the value to sort on when you want the order the project itself uses — see [List work item types](/api-reference/v2/work-item-types/list-work-item-types).
+
+- `logo_props` _any_
+
+ The icon and background color rendered next to the type. Generated by Plane when the type is created, so it is read-only here.
+
+- `created_at` _string (date-time)_
+
+ When the type was created.
+
+::: info external_id is write-only
+`external_id` and `external_source` are accepted on create and update as correlation fields for sync and import, but they are **not returned** in the read shape. Neither is `updated_at`. To find a type you previously synced, keep your own mapping from `external_id` to the returned `id`.
+:::
+
+
+
+
+
+
+```json
+{
+ "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:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-item-types/{pk}/
+
+
+
+
+
+Rename a type, rewrite its description, retire it from pickers, or correct its sync correlation fields. Work items already using the type are untouched — you are editing the type, not retyping anything.
+
+`PATCH` is partial. Send only the fields you want to change; anything you omit keeps its current value. Omitting a field is not the same as sending `null`.
+
+::: warning This write requires project mode
+If the workspace manages types at the workspace level, this returns `409 work_item_types_managed_at_workspace`. Edit the type on [the workspace surface](/api-reference/v2/workspace-work-item-types/update-workspace-work-item-type) instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the type belongs to.
+
+
+
+
+
+The id of the work item type to update.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional — send the subset you are changing.
+
+
+
+
+
+New display name for the type. Maximum 255 characters. Renaming is safe: work items reference the type by `type_id`, not by name.
+
+
+
+
+
+What this type is for. It is returned as `type_description` by the [schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema), so this is the field to edit when integrations are choosing the wrong type.
+
+
+
+
+
+Whether the type can be assigned to new work items. Setting it to `false` retires the type from pickers without deleting it — existing work items keep the type and stay readable. This is the safe alternative to [delete](/api-reference/v2/work-item-types/delete-work-item-type), which a type in use rejects.
+
+
+
+
+
+Your system's identifier for this type, for sync and import correlation. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters, nullable.
+
+
+
+
+
+
+::: info is_default, is_epic and level are not accepted here
+`is_default` moves through [mark-default](/api-reference/v2/work-item-types/mark-default-work-item-type), which is a dedicated request precisely because promoting one type demotes another. `is_epic` and `level` are read-only, as is `logo_props`.
+:::
+
+
+
+### Scopes
+
+`projects.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `400` | `validation_error` | A field over its 255-character limit, or `"is_active": false` on the default type. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't update work item types. |
+| `404` | `resource_not_found` | No such type, project, or workspace — or the type belongs to another project. |
+| `409` | `work_item_types_managed_at_workspace` | The workspace manages types at the workspace level. Use the workspace surface. |
+| `409` | `conflict` | Another type in this project already uses this `external_id` and `external_source` pair. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Defect",
+ "description": "A verified regression in shipped behavior"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Defect",
+ "description": "A verified regression in shipped behavior",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-types/d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Defect",
+ description: "A verified regression in shipped behavior",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "d1e7a4c9-2b58-4f36-9a0e-7c3b5d81f240",
+ "name": "Defect",
+ "description": "A verified regression in shipped behavior",
+ "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"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/validation_error",
+ "title": "Validation Error",
+ "status": 400,
+ "code": "validation_error",
+ "detail": "The default work item type cannot be deactivated.",
+ "errors": []
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/archive/
+
+
+
+
+
+Archive a work item: stamp `archived_at` with the current time and take it out of the active work item set.
+
+This is a **bodyless** `POST` — send no JSON at all. The response is the full work item in its usual read shape, with
+`archived_at` now populated, so you can confirm the change without a follow-up read.
+
+Archiving is reversible with [Unarchive a work item](/api-reference/v2/work-items/unarchive-work-item), and it is
+entirely separate from [deleting](/api-reference/v2/work-items/delete-work-item) — an archived work item still exists.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. The endpoint takes no request body; anything you send is ignored.
+
+
+
+::: warning Archiving twice returns 404
+Once archived, a work item is outside the default query set, so a second `archive` call on the same work item can't
+resolve it and returns `404 resource_not_found` — not a `409`, and not a silent success. If you're re-running a job,
+treat a `404` here as "already archived" rather than an error worth retrying.
+:::
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ---------------------------------------------------------------------------------- |
+| `400` | `validation_error` | The request could not be processed — for example a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't archive this work item. |
+| `404` | `resource_not_found` | No such work item, it's outside your project or tenant, or it is already archived. |
+| `409` | `conflict` | The write collides with a protected-resource constraint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/archive/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/archive/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json()["archived_at"])
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/archive/",
+ {
+ method: "POST",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": "2026-02-03T11:47:19.204518Z",
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource_not_found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/
+
+
+
+
+
+Create a work item in a project. Only `name` is required — everything else falls back to the project's defaults, so the
+smallest useful create is one field.
+
+Each relation accepts either its id field or a **write-only human-readable parallel**: `state` instead of `state_id`,
+`assignees` (emails) instead of `assignee_ids`, `labels` (names) instead of `label_ids`, and so on. Send one or the
+other, never both. This is what lets an importer or an agent write a fully-populated work item without first resolving
+six UUIDs.
+
+The response is the standard sparse read shape, with `custom_fields` populated.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to create the work item in.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Title of the work item. Maximum 255 characters. The only required field.
+
+
+
+
+
+Rich-text body as HTML, for example `Steps to reproduce…
`. The HTML is sanitized on the way in; content that
+can't be sanitized is rejected with a `400`.
+
+`description_html` is **not** part of the read shape, so it will not appear in the response.
+
+
+
+
+
+One of `urgent`, `high`, `medium`, `low`, `none`. Defaults to `none`.
+
+
+
+
+
+The workflow state to create the work item in. Must be a state of this project. Omit it and the work item lands in the
+project's default state.
+
+
+
+
+
+The state's **name** instead of its id, for example `In Progress`. Matched case-insensitively within the project.
+Write-only.
+
+Unknown name or a name that matches more than one state is a `400`. Sending both `state` and `state_id` is a `400`.
+
+
+
+
+
+The work item type. Accepts a type owned by the project and a workspace-level type imported into it. Requires work item
+types to be enabled.
+
+
+
+
+
+The type's **name** instead of its id, for example `Bug`. Matched case-insensitively among the project's non-epic
+types. Write-only.
+
+
+
+
+
+The parent work item. The parent must be in the same workspace, but it may live in a different project.
+
+
+
+
+
+The parent's **identifier** instead of its id, for example `PROJ-118`. Resolved within the workspace. Write-only.
+
+
+
+
+
+User ids to assign. Each must be an active, assignable member of the project.
+
+Leave it out and the project's default assignee is applied, if one is configured. Send `[]` to create the work item
+with no assignee at all.
+
+
+
+
+
+Member **email addresses** instead of ids, for example `["ana@example.com"]`. Every address must belong to an active,
+assignable project member — any that don't are named in the `400`. Write-only.
+
+
+
+
+
+Label ids to apply. Each must be a label of this project, or a workspace-level label available to it.
+
+
+
+
+
+Label **names** instead of ids, for example `["regression", "auth"]`. Matched case-insensitively against the project's
+labels and the workspace-level labels available to it. A name that exists at both levels is ambiguous and returns a
+`400` telling you to use `label_ids`. Write-only.
+
+
+
+
+
+The estimate point to assign, from the project's active estimate system.
+
+
+
+
+
+The estimate point's **value** instead of its id, for example `5` or `L`. Resolved against the project's active
+estimate. Write-only.
+
+
+
+
+
+Planned start, for example `2026-01-12`. Must not be after `target_date`.
+
+
+
+
+
+Planned due date, for example `2026-01-20`.
+
+
+
+
+
+Your system's identifier for this work item, for sync and import correlation. Maximum 255 characters.
+
+Stored and filterable on [List work items](/api-reference/v2/work-items/list-work-items), but not returned on reads.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+
+::: info Setting custom property values
+Work item type custom properties are written through a separate `custom_fields` object on the request body, keyed by
+property name, and are validated against the type you selected. Its shape depends on the type you chose, so it is not
+declared in the OpenAPI schema — read it from
+[the type's schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema). It requires custom
+properties to be enabled for the workspace — sending it otherwise is a `400`. Properties you omit are filled from the
+type's defaults. See [work item properties](/api-reference/v2/work-item-properties/list-work-item-properties).
+:::
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `validation_error` | Missing `name`; a bad `priority`; `start_date` after `target_date`; an unresolvable or ambiguous `state`/`type`/`parent`/`assignees`/`labels`/`estimate`; both a name and its `*_id`; or an id from another project or workspace. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't create work items in this project. |
+| `403` | `workflow_transition_denied` | A workflow rule forbids creating a work item in the requested state. |
+| `404` | `resource_not_found` | No such workspace or project, or it's outside your tenant. |
+| `409` | `conflict` | The write collides with a uniqueness or protected-resource constraint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Fix login redirect loop",
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "target_date": "2026-01-20"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Fix login redirect loop",
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "target_date": "2026-01-20",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Fix login redirect loop",
+ priority: "high",
+ state_id: "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ assignee_ids: ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ target_date: "2026-01-20",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": null,
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": [],
+ "parent_id": null,
+ "start_date": null,
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {}
+}
+```
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Fix login redirect loop",
+ "state": "In Progress",
+ "type": "Bug",
+ "parent": "PROJ-118",
+ "assignees": ["ana@example.com"],
+ "labels": ["regression", "auth"],
+ "estimate": "5"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Fix login redirect loop",
+ "state": "In Progress",
+ "type": "Bug",
+ "parent": "PROJ-118",
+ "assignees": ["ana@example.com"],
+ "labels": ["regression", "auth"],
+ "estimate": "5",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Fix login redirect loop",
+ state: "In Progress",
+ type: "Bug",
+ parent: "PROJ-118",
+ assignees: ["ana@example.com"],
+ labels: ["regression", "auth"],
+ estimate: "5",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/validation_error",
+ "title": "Validation Error",
+ "status": 400,
+ "code": "validation_error",
+ "detail": "The request body failed validation.",
+ "errors": [{ "field": "state", "message": "No state named 'In Reviewing' in this project." }]
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/
+
+
+
+
+
+Delete a work item. The delete is a soft delete — the row is retained internally — but it is gone from every API
+surface, and there is no endpoint to bring it back.
+
+A successful delete returns `204` with an empty body. Deleting a work item that is already gone returns `404`, so the
+call is not idempotent from the client's point of view.
+
+If you want the work item out of the way but recoverable, use
+[Archive a work item](/api-reference/v2/work-items/archive-work-item) instead.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+::: warning Deleting is not reversible through the API
+There is no undelete endpoint. Confirm with the user before wiring this into an automation, and prefer archiving for
+anything you might want back.
+:::
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | -------------------------------------------------------------------------------- |
+| `400` | `validation_error` | The request could not be processed — for example a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't delete this work item. |
+| `404` | `resource_not_found` | No such work item, or it's outside your project or tenant. |
+| `409` | `conflict` | The delete collides with a protected-resource constraint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "DELETE",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+No content.
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/forbidden",
+ "title": "Forbidden",
+ "status": 403,
+ "code": "forbidden",
+ "detail": "You do not have permission to delete this work item."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-items/{identifier}/
+
+
+
+
+
+Retrieve a work item by its human key — `PROJ-142` — anywhere in the workspace.
+
+This route exists for callers that **don't know the project UUID**. A `PROJ-142` in a commit message, a chat command, a
+support ticket, or an LLM prompt carries no project id, and making the caller first list projects, find the one whose
+identifier is `PROJ`, and then call the project-scoped route would be three requests to answer one question. Here it is
+one request against the workspace.
+
+The route is read-only. Creates, updates, deletes, and archiving all go through the project-scoped UUID routes.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The work item's human key: the project identifier, a hyphen, and the work item's number — `PROJ-142`.
+
+The project part must start with a letter, and it is upper-cased before lookup, so `proj-142` resolves the same work
+item as `PROJ-142`. A project identifier is unique within a workspace, which is what makes this key unambiguous.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `state`, `type`, `parent`, `assignees`, `labels`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. An unknown value is
+a `400`.
+
+
+
+
+
+
+::: info Everything unresolvable is a 404
+A malformed key (`PROJ_142`, `142`, `-142`), a key from a project you can't see, a key in another workspace, and a key
+that resolves to nothing all return the same `404`. That is deliberate: the response never reveals whether a work item
+exists, only whether _you_ can read it. Archived work items are not served from this route either.
+:::
+
+
+
+### Scopes
+
+`projects.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | --------------------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your token scope can't read work items. |
+| `404` | `resource_not_found` | Malformed identifier, no such work item, it's outside your tenant or visibility, or archived. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-items/PROJ-142/", {
+ method: "GET",
+ headers: { "X-Api-Key": "your-api-key" },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource_not_found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/
+
+
+
+
+
+Retrieve one work item by its UUID. This is the endpoint to use after a list call, or any time you already hold the
+work item's `id`.
+
+Unlike the list endpoint, this response populates `custom_fields` — the work item type's custom property values, keyed
+by property name. If you only have a `PROJ-142`-style key and not the project UUID, use
+[Get a work item by identifier](/api-reference/v2/work-items/get-work-item-by-identifier) instead.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `state`, `type`, `parent`, `assignees`, `labels`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. An unknown value is
+a `400`.
+
+
+
+
+
+
+::: warning Archived work items are not returned
+An archived work item sits outside the default query set, so a read of one returns `404` — the same response as a work
+item that never existed. [Unarchive](/api-reference/v2/work-items/unarchive-work-item) it first if you need to read it
+again. See [Archive a work item](/api-reference/v2/work-items/archive-work-item).
+:::
+
+
+
+### Scopes
+
+`projects.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ----------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read work items in this project. |
+| `404` | `resource_not_found` | No such work item, it belongs to another project or tenant, or it's archived. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "GET",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {},
+ "state": {
+ "id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "name": "In Progress",
+ "color": "#3f76ff",
+ "group": "started"
+ },
+ "assignees": [
+ {
+ "id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "display_name": "ana",
+ "avatar_url": "https://assets.plane.so/avatars/ana.png",
+ "email": "ana@example.com"
+ }
+ ]
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/
+
+
+
+
+
+List the work items in a project. This is the endpoint you build reports, syncs, and board views on: it takes a wide
+set of filters, orders by stored columns or by meaning, and paginates by offset or by cursor.
+
+Results are always scoped to the project in the path and to what your token is allowed to see. Filters can only narrow
+that set — they never widen it.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project to list work items from.
+
+
+
+
+
+
+
+
+### Filters
+
+Every filter is optional, and filters combine with AND. Each concept below has a base parameter plus the `__in` and
+`__isnull` variants noted in its description.
+
+
+
+
+
+Match work items in a specific state. Use `state_id__in` with a comma-separated list to match any of several states.
+
+
+
+
+
+Match by the state's workflow group instead of a specific state — stable across projects that name their states
+differently. One of `backlog`, `unstarted`, `started`, `completed`, `cancelled`, `triage`.
+
+Use `state_group__in` for several groups, for example `?state_group__in=started,completed`.
+
+
+
+
+
+One of `urgent`, `high`, `medium`, `low`, `none`. Use `priority__in` for several, for example
+`?priority__in=urgent,high`.
+
+
+
+
+
+Match work items assigned to a user. `assignee_id__in` matches any of several users; `assignee_id__isnull=true`
+returns only unassigned work items.
+
+
+
+
+
+Match work items carrying a label. `label_id__in` matches any of several labels; `label_id__isnull=true` returns only
+unlabeled work items.
+
+
+
+
+
+Match work items of a given work item type. `type_id__in` accepts a comma-separated list.
+
+
+
+
+
+Match the children of a work item. `parent_id__in` accepts several parents; `parent_id__isnull=true` returns only
+top-level work items.
+
+
+
+
+
+Match work items in a cycle. `cycle_id__in` accepts several cycles; `cycle_id__isnull=true` returns the backlog of
+work items in no cycle at all.
+
+
+
+
+
+Match work items in a module. `module_id__in` accepts several modules; `module_id__isnull=true` returns work items in
+no module.
+
+
+
+
+
+Match the single work item with this number within the project — the `142` of `PROJ-142`.
+
+
+
+
+
+Filter drafts in or out. Drafts are work items still being composed in the Plane app.
+
+
+
+
+
+Correlation filters for sync and import. `external_source` is the system a record came from and `external_id` is its
+key there, so the pair is how you find the Plane work item that mirrors a row in your own database.
+
+These values are not returned on reads — the lookup is one-way.
+
+
+
+
+
+Bound the creation timestamp. Pass an ISO 8601 datetime, for example `2026-01-01T00:00:00Z`. Use both for a window.
+
+
+
+
+
+Bound the last-modified timestamp. This is the pair to use for incremental sync — poll with
+`?updated_at__gte=&order_by=updated_at`.
+
+`updated_at` is filterable and orderable but is not part of the read shape, so it does not come back in the response
+body.
+
+
+
+
+
+Bound the planned start date, for example `2026-01-01`.
+
+
+
+
+
+Bound the planned due date. `?target_date__lte=2026-01-31&state_group__in=backlog,unstarted,started` is the "what is
+about to slip" query.
+
+
+
+
+
+
+
+
+### Search and ordering
+
+
+
+
+
+Free-text search over the work item name.
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending. Defaults to `-created_at`.
+
+- `created_at`, `-created_at`
+- `updated_at`, `-updated_at`
+- `sequence_id`, `-sequence_id`
+- `id`, `-id`
+- `sort_order`, `-sort_order` — the manual board ordering
+- `priority`, `-priority` — semantic: `urgent` → `high` → `medium` → `low` → `none`, not alphabetical
+- `state_group`, `-state_group` — semantic: workflow order, not alphabetical
+
+`priority` and `state_group` sort by meaning, which is what you want for a board but is not cursor-eligible. Pair
+either with `?paginate=cursor` and you get `400 ordering_not_cursor_eligible`; use the default offset pages instead.
+
+
+
+
+
+
+
+
+### Pagination
+
+Offset is the default. Cursor is opt-in per request.
+
+
+
+
+
+Page size. Defaults to 50, maximum 200.
+
+
+
+
+
+Rows to skip from the start of the result set. Maximum 10000 — past that, switch to cursor pagination.
+
+
+
+
+
+Defaults to `true`. Pass `?count=false` to skip the `COUNT(*)` and omit `total_count` from the envelope. Worth doing on
+large projects when you only need the rows.
+
+
+
+
+
+Set to `cursor` to opt into keyset pagination. The envelope changes to `next_cursor` / `has_more` and drops
+`total_count`. Use it for deep or long-running traversals where offset pages would drift as rows are inserted. Follow
+the returned `next_cursor` as described in [Pagination](/api-reference/v2/pagination).
+
+
+
+
+
+
+
+
+### Expansion
+
+
+
+
+
+Comma-separated relations to embed alongside the ids: `state`, `type`, `parent`, `assignees`, `labels`.
+
+Expansion is separate-key — `?expand=state` keeps `state_id` and adds a `state` object next to it. An unknown value is
+a `400`.
+
+
+
+
+
+
+::: warning Bad filter values fail loudly, bad `order_by` does not
+The enum-backed _filters_ (`priority`, `priority__in`, `state_group`, `state_group__in`) are validated against their
+allowed values. A typo returns `400 validation_error` naming the parameter — it does not silently return an empty page.
+Treat an empty `data` array as a genuine "no matches".
+
+`order_by` and `paginate` are the exception: neither is validated. An unrecognized `order_by` silently falls back to the
+default ordering, and anything other than `paginate=cursor` silently uses offset pagination — so check your spelling
+there, because a typo shows up as an unexpected sort order or envelope rather than an error.
+:::
+
+::: info Archived work items are excluded
+The list returns active work items only — anything with `archived_at` set is filtered out, so archiving a work item
+takes it off every page of this list. See [Archive a work item](/api-reference/v2/work-items/archive-work-item).
+:::
+
+
+
+### Scopes
+
+`projects.work_items:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | --------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read work items in this project. |
+| `404` | `resource_not_found` | No such workspace or project, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/?state_group__in=started,unstarted&priority=high&per_page=50&order_by=-created_at" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={
+ "state_group__in": "started,unstarted",
+ "priority": "high",
+ "per_page": 50,
+ "order_by": "-created_at",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({
+ state_group__in: "started,unstarted",
+ priority: "high",
+ per_page: "50",
+ order_by: "-created_at",
+});
+
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/?${params}`,
+ {
+ method: "GET",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": null
+ },
+ {
+ "id": "3b7d9e40-1c62-4a85-b0f3-9d5c2e6a8471",
+ "name": "Rate limit the invite endpoint",
+ "identifier": "PROJ-141",
+ "sequence_id": 141,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": null,
+ "assignee_ids": [],
+ "label_ids": [],
+ "parent_id": "a7e51d24-3b98-4c6d-9f10-7d2c8e4b5a61",
+ "start_date": null,
+ "target_date": null,
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-13T16:04:02.911204Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": null
+ }
+ ],
+ "next": 50,
+ "previous": null,
+ "total_count": 327,
+ "pagination": { "style": "offset" }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": null
+ }
+ ],
+ "next_cursor": "b3A9MTcxJmxpbWl0PTUw",
+ "has_more": true,
+ "pagination": { "style": "cursor" }
+}
+```
+
+
+
+
+
+
+
+## The work item object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the work item. This is the `{pk}` on every project-scoped detail route.
+
+- `name` _string_
+
+ Title of the work item. Maximum 255 characters.
+
+- `identifier` _string_
+
+ The human key, for example `PROJ-142`. It is the project's identifier joined to `sequence_id`, and it is what people
+ paste into chat and commit messages. Use it with
+ [Get a work item by identifier](/api-reference/v2/work-items/get-work-item-by-identifier) when you don't have the
+ project UUID.
+
+- `sequence_id` _integer_
+
+ The work item's number within its project. Assigned by Plane and never reused.
+
+- `priority` _string_
+
+ One of `urgent`, `high`, `medium`, `low`, or `none`. Never null — an unprioritized work item reads `none`.
+
+- `state_id` _string (uuid)_
+
+ The workflow state the work item is currently in.
+
+- `type_id` _string (uuid)_
+
+ The work item type. `null` when the project has no types enabled or the item is untyped.
+
+- `assignee_ids` _array of string_
+
+ User ids assigned to the work item. Empty array when unassigned.
+
+- `label_ids` _array of string_
+
+ Label ids applied to the work item. Empty array when unlabeled.
+
+- `parent_id` _string (uuid)_
+
+ The parent work item, or `null` for a top-level item. A parent may live in another project of the same workspace.
+
+- `start_date` _string (date)_
+
+ Planned start, or `null`.
+
+- `target_date` _string (date)_
+
+ Planned due date, or `null`.
+
+- `is_draft` _boolean_
+
+ Whether the work item is still a draft. Drafts are created in the Plane app and are excluded from most boards.
+
+- `archived_at` _string (date-time)_
+
+ When the work item was archived, or `null` if it is active. See [Archiving](#archiving-and-deleting).
+
+- `created_at` _string (date-time)_
+
+ When the work item was created.
+
+- `created_by_id` _string (uuid)_
+
+ The user who created the work item. `null` for items created by an automation with no acting user.
+
+- `custom_fields` _object_
+
+ Values of the work item type's custom properties, keyed by property name. **Populated only on single-item
+ responses** — it is always `null` on the list endpoint. See [Custom fields](#custom-fields).
+
+::: info The read shape is sparse and fixed
+`description_html`, `external_id`, `external_source`, and `estimate_point_id` are accepted on writes but are **not**
+part of the read shape — they will not come back on any response. There is also no `updated_at`, no `project_id`, and
+no `workspace_id`: you already know the project from the path.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ },
+ "root_cause": {
+ "id": "9e3b6c21-7f45-4d80-a1e9-5c8b2d7f4a36",
+ "value": "Stale session cookie",
+ "value_detail": null
+ }
+ }
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/unarchive/
+
+
+
+
+
+Restore an archived work item: clear `archived_at` and put it back into the active set, where it shows up in lists and
+plain detail reads again.
+
+This is a **bodyless** `POST` — send no JSON at all. The response is the full work item in its usual read shape with
+`archived_at` back to `null`.
+
+Unlike most detail routes, this one deliberately looks past the archive filter to find the work item — that is the
+whole point. It also means the call is safe to repeat: unarchiving a work item that isn't archived succeeds and changes
+nothing.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. The endpoint takes no request body; anything you send is ignored.
+
+
+
+::: tip Safe to retry
+Unarchive resolves archived and active work items alike, so a repeat call is a no-op that returns `200` with
+`archived_at: null`. Archive is the asymmetric one — see
+[Archive a work item](/api-reference/v2/work-items/archive-work-item).
+:::
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | -------------------------------------------------------------------------------- |
+| `400` | `validation_error` | The request could not be processed — for example a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't archive or unarchive this work item. |
+| `404` | `resource_not_found` | No such work item, or it's outside your project or tenant. |
+| `409` | `conflict` | The write collides with a protected-resource constraint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/unarchive/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/unarchive/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json()["archived_at"]) # None
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/unarchive/",
+ {
+ method: "POST",
+ headers: { "X-Api-Key": "your-api-key" },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "high",
+ "state_id": "f960d3c2-8524-4a41-b8eb-055ce4be2a7f",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": "2026-01-20",
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource_not_found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/projects/{project_id}/work-items/{pk}/
+
+
+
+
+
+Update a work item. Every field is optional and the update is partial — send only what changes, and everything you
+leave out stays exactly as it was.
+
+Omitting a field is not the same as sending `null`. Omit `target_date` and the existing due date is preserved; send
+`"target_date": null` and it is cleared.
+
+There is no `PUT` in v2. A `PUT` to this path returns `405 method_not_allowed`.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The project the work item belongs to.
+
+
+
+
+
+The work item's UUID. This lookup is UUID-only — a `PROJ-142` identifier here returns `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+New title. Maximum 255 characters.
+
+
+
+
+
+Replacement rich-text body as HTML. Sanitized on the way in; content that can't be sanitized is rejected with a `400`.
+Not part of the read shape, so it won't appear in the response.
+
+
+
+
+
+One of `urgent`, `high`, `medium`, `low`, `none`.
+
+
+
+
+
+Move the work item to another state of the same project. This is the field workflow rules police — see
+[Workflow rules](#workflow-rules-can-reject-a-transition).
+
+
+
+
+
+The target state's **name** instead of its id, for example `Done`. Matched case-insensitively within the project.
+Write-only. Sending both `state` and `state_id` is a `400`.
+
+
+
+
+
+Change the work item type. Send `null` to make the work item untyped.
+
+
+
+
+
+The type's **name** instead of its id, for example `Bug`. Write-only.
+
+
+
+
+
+Re-parent the work item. The parent must be in the same workspace and may be in a different project. Send `null` to
+detach it and make it top-level.
+
+
+
+
+
+The parent's **identifier** instead of its id, for example `PROJ-118`. Write-only.
+
+
+
+
+
+**Replaces** the whole assignee set — it is not additive. Send the complete list you want, `[]` to unassign everyone,
+or omit the field to leave assignees untouched.
+
+
+
+
+
+Member **email addresses** instead of ids. Same replace-the-set semantics. Every address must belong to an active,
+assignable project member. Write-only.
+
+
+
+
+
+**Replaces** the whole label set. Send `[]` to strip all labels, or omit the field to leave them untouched.
+
+
+
+
+
+Label **names** instead of ids. Same replace-the-set semantics. A name that exists at both project and workspace level
+is ambiguous and returns a `400` telling you to use `label_ids`. Write-only.
+
+
+
+
+
+Change the estimate point, from the project's active estimate system. Send `null` to clear the estimate.
+
+
+
+
+
+The estimate point's **value** instead of its id, for example `5`. Write-only.
+
+
+
+
+
+Planned start, or `null` to clear it. Must not be after `target_date`.
+
+
+
+
+
+Planned due date, or `null` to clear it.
+
+
+
+
+
+Your system's identifier for this work item. Maximum 255 characters. Filterable on
+[List work items](/api-reference/v2/work-items/list-work-items), but not returned on reads.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+
+::: info Fields you cannot patch
+`id`, `identifier`, `sequence_id`, `is_draft`, `archived_at`, `created_at`, and `created_by_id` are read-only — sending
+them has no effect. In particular, archiving is not a `PATCH` on `archived_at`; use
+[Archive a work item](/api-reference/v2/work-items/archive-work-item).
+
+Custom property values go through a separate `custom_fields` object on the request body, keyed by property name — its
+shape follows the work item's type, so it is not declared in the OpenAPI schema. See
+[the type's schema endpoint](/api-reference/v2/work-item-types/get-work-item-type-schema). On a `PATCH` only the
+properties you submit are replaced; untouched properties keep their values and are never required-checked.
+:::
+
+
+
+### Scopes
+
+`projects.work_items:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `validation_error` | A bad `priority`; `start_date` after `target_date`; an unresolvable or ambiguous `state`/`type`/`parent`/`assignees`/`labels`/`estimate`; both a name and its `*_id`; or an id from another project or workspace. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't edit this work item. |
+| `403` | `workflow_transition_denied` | A workflow rule forbids the requested state transition. |
+| `404` | `resource_not_found` | No such work item, or it's outside your project or tenant. |
+| `409` | `conflict` | The write collides with a uniqueness or protected-resource constraint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "priority": "urgent",
+ "state": "In Review",
+ "assignees": ["ana@example.com", "rk@example.com"],
+ "target_date": null
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "priority": "urgent",
+ "state": "In Review",
+ "assignees": ["ana@example.com", "rk@example.com"],
+ "target_date": None,
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b" +
+ "/work-items/8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ priority: "urgent",
+ state: "In Review",
+ assignees: ["ana@example.com", "rk@example.com"],
+ target_date: null,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "8f4c2b1e-0d3a-4f7b-9c21-6e5a8b7d4f13",
+ "name": "Fix login redirect loop",
+ "identifier": "PROJ-142",
+ "sequence_id": 142,
+ "priority": "urgent",
+ "state_id": "5d2a91b7-64c0-4f38-b9e2-0a3f7c6d8149",
+ "type_id": "2d9d1a97-5c6f-4a1e-9d5b-8c2f7e30b6a4",
+ "assignee_ids": ["16c61a3a-512a-48ac-b0be-b6b46fe6f430", "9b7f4c53-2d18-4a6e-8c05-1f3e7d9a2b64"],
+ "label_ids": ["c1b8f3d6-9a44-4e12-8f7a-2b6d5c9e1a03"],
+ "parent_id": null,
+ "start_date": "2026-01-12",
+ "target_date": null,
+ "is_draft": false,
+ "archived_at": null,
+ "created_at": "2026-01-14T09:22:41.478363Z",
+ "created_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430",
+ "custom_fields": {
+ "severity": {
+ "id": "b52e7c18-4d3f-4a90-8e61-0f7a3c9d2b45",
+ "value": "Sev-1",
+ "value_detail": {
+ "id": "7c0a5f39-2e84-4b17-9a6c-1d8e4f2b60c9",
+ "name": "Sev-1",
+ "logo_props": {}
+ }
+ }
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/workflow_transition_denied",
+ "title": "Forbidden",
+ "status": 403,
+ "code": "workflow_transition_denied",
+ "detail": "State transition is not allowed."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/features/
+
+
+
+
+
+Read the workspace's feature flags. There is one feature record per workspace, so this returns a single object rather than a list.
+
+Call it during client start-up. `is_work_item_types_enabled` tells you which surface accepts work item type and property writes, and the remaining flags tell you which parts of your UI or sync are worth showing at all.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+None. This endpoint takes no filters, no pagination, and no `?expand=` — passing one is not a supported way to widen the response.
+
+
+
+
+
+### Scopes
+
+`workspaces.features:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | -------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's features. |
+| `404` | `resource_not_found` | No such workspace, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: tip This is the mode check
+`is_work_item_types_enabled: true` means the workspace manages work item types at the **workspace** level; `false` means each **project** does. Writes sent to the other surface return `409`, with `work_item_types_managed_at_workspace` or `work_item_types_managed_at_project`. Reads are unaffected. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+::: info Cache it, but not forever
+The flags change rarely, so caching the response for the life of a request batch is reasonable. Re-read it whenever a write returns `409 work_item_types_managed_at_workspace` or `work_item_types_managed_at_project` — that code means your cached mode is stale.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/features/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/features/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+features = response.json()
+
+if features["is_work_item_types_enabled"]:
+ base = "https://api.plane.so/api/v2/workspaces/my-team" # workspace mode
+else:
+ base = "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b"
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/features/", {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const features = await response.json();
+const workspaceMode = features.is_work_item_types_enabled;
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a72f1c40-5b8e-4d19-9f2a-3c6d8e1b7a55",
+ "is_work_item_types_enabled": true,
+ "work_item_type_default_level": 0,
+ "is_workitem_hierarchy_enabled": false,
+ "is_project_grouping_enabled": false,
+ "is_teams_enabled": true,
+ "is_wiki_enabled": true,
+ "is_initiative_enabled": false,
+ "is_customer_enabled": false,
+ "is_release_enabled": false,
+ "is_state_duration_enabled": false,
+ "is_pi_enabled": false,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource_not_found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "No Workspace matches the given query."
+}
+```
+
+
+
+
+
+
+
+## The workspace feature object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the workspace's feature record.
+
+- `is_work_item_types_enabled` _boolean_
+
+ Whether work item types are managed at the **workspace** level. `true` means workspace mode — types and properties are defined once for the workspace and imported into projects. `false` means project mode — each project owns its own types. This is the field to read before any type or property write. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+
+- `work_item_type_default_level` _integer_
+
+ The default level applied to work item types in this workspace. The schema constrains it to an integer and declares no enum, so treat any value as legal and leave it as returned unless you are deliberately changing type levels.
+
+- `is_workitem_hierarchy_enabled` _boolean_
+
+ Whether work items can be nested into a parent and child hierarchy in this workspace.
+
+- `is_project_grouping_enabled` _boolean_
+
+ Whether projects can be organized into groups in the workspace.
+
+- `is_teams_enabled` _boolean_
+
+ Whether teamspaces are available. Teamspaces have their own endpoints under the `teamspaces:*` scopes.
+
+- `is_wiki_enabled` _boolean_
+
+ Whether the workspace-level wiki is available, behind the `wiki.pages:*` scopes.
+
+- `is_initiative_enabled` _boolean_
+
+ Whether initiatives — the layer that groups projects and epics toward a larger outcome — are available.
+
+- `is_customer_enabled` _boolean_
+
+ Whether customers and customer requests are available, behind the `customers:*` scopes.
+
+- `is_release_enabled` _boolean_
+
+ Whether releases are available, behind the `releases:*` scopes.
+
+- `is_state_duration_enabled` _boolean_
+
+ Whether Plane records how long work items spend in each state.
+
+- `is_pi_enabled` _boolean_
+
+ Whether Pi, Plane's AI assistant, is available in the workspace.
+
+- `created_at` _string (date-time)_
+
+ When the feature record was created.
+
+::: warning Watch the spelling of the hierarchy flag
+It is `is_workitem_hierarchy_enabled` — no underscore between `work` and `item` — while its neighbor is `is_work_item_types_enabled`. Unknown keys in a `PATCH` body do not toggle anything, so a misspelling looks like a silent no-op. Read the response back and confirm the flag actually moved.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "a72f1c40-5b8e-4d19-9f2a-3c6d8e1b7a55",
+ "is_work_item_types_enabled": true,
+ "work_item_type_default_level": 0,
+ "is_workitem_hierarchy_enabled": false,
+ "is_project_grouping_enabled": false,
+ "is_teams_enabled": true,
+ "is_wiki_enabled": true,
+ "is_initiative_enabled": false,
+ "is_customer_enabled": false,
+ "is_release_enabled": false,
+ "is_state_duration_enabled": false,
+ "is_pi_enabled": false,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/features/
+
+
+
+
+
+Turn workspace features on or off. The update is partial — send only the flags you want to change, and every field you omit keeps its current value. Omitting a field is not the same as sending `null`.
+
+The response is the full feature object after the change, so you never need a follow-up `GET` to confirm what happened.
+
+::: warning Toggling `is_work_item_types_enabled` moves the write surface
+This flag decides whether work item types are managed at the workspace or the project level. Flipping it changes which endpoints accept type and property writes **for every client in the workspace**, and in-flight integrations start getting `409` from the surface they were using. Treat it as an administrative action, not a runtime decision. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional. `id` and `created_at` are read-only — sending them has no effect.
+
+
+
+
+
+Manage work item types at the workspace level (`true`) or per project (`false`). This is the work item type mode switch — read [Work item type modes](/api-reference/v2/work-item-type-modes) before changing it.
+
+
+
+
+
+The default level applied to work item types in this workspace. The schema declares no enum and no bounds, so it accepts any integer.
+
+
+
+
+
+Allow work items to be nested into a parent and child hierarchy. Note the spelling — no underscore between `work` and `item`.
+
+
+
+
+
+Allow projects to be organized into groups in the workspace.
+
+
+
+
+
+Enable teamspaces for the workspace.
+
+
+
+
+
+Enable the workspace-level wiki.
+
+
+
+
+
+Enable initiatives, the layer that groups projects and epics toward a larger outcome.
+
+
+
+
+
+Enable customers and customer requests.
+
+
+
+
+
+Enable releases.
+
+
+
+
+
+Record how long work items spend in each state.
+
+
+
+
+
+Enable Pi, Plane's AI assistant, in the workspace.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.features:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `validation_error` | A flag was sent with a non-boolean value, or `work_item_type_default_level` was not an integer. Includes an `errors[]` array naming the field. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't change this workspace's features. |
+| `404` | `resource_not_found` | No such workspace, or it's outside your tenant. |
+| `409` | `conflict` | The requested toggle conflicts with the workspace's current state and was not applied. Re-read the object before retrying. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: info Unknown keys are not toggles
+A body key that is not one of the fields above is not a flag and does not change anything. Always compare the response object against what you sent rather than assuming a `200` means your flag moved; `is_workitem_hierarchy_enabled` in particular is easy to mistype as `is_work_item_hierarchy_enabled`.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/features/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "is_work_item_types_enabled": true,
+ "is_state_duration_enabled": true
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/features/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "is_work_item_types_enabled": True,
+ "is_state_duration_enabled": True,
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/features/", {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ is_work_item_types_enabled: true,
+ is_state_duration_enabled: true,
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a72f1c40-5b8e-4d19-9f2a-3c6d8e1b7a55",
+ "is_work_item_types_enabled": true,
+ "work_item_type_default_level": 0,
+ "is_workitem_hierarchy_enabled": false,
+ "is_project_grouping_enabled": false,
+ "is_teams_enabled": true,
+ "is_wiki_enabled": true,
+ "is_initiative_enabled": false,
+ "is_customer_enabled": false,
+ "is_release_enabled": false,
+ "is_state_duration_enabled": true,
+ "is_pi_enabled": false,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/validation_error",
+ "title": "Validation Error",
+ "status": 400,
+ "code": "validation_error",
+ "detail": "Invalid input.",
+ "errors": [{ "field": "is_teams_enabled", "message": "Must be a valid boolean." }]
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-properties/
+
+
+
+
+
+Define a custom property once for the whole workspace. `display_name` and `property_type` are the only
+required fields; everything else refines how the value is captured.
+
+::: warning A new property is not live yet
+Creating a property adds it to the workspace catalog. It appears on work items only once a **context** binds
+it to projects and work item types. Follow this call with
+[Create a property context](/api-reference/v2/work-item-property-contexts/create-property-context), or the
+property will sit in the catalog unused.
+:::
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Create the property on the project-level resource instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The label shown wherever the property is rendered. Maximum 255 characters.
+
+
+
+
+
+What kind of value the property holds. Choose carefully — it governs what `relation_type`, `options`,
+`settings`, and `validation_rules` mean.
+
+- `TEXT` — free-form text
+- `DATETIME` — a date and time
+- `DECIMAL` — a number
+- `BOOLEAN` — true or false
+- `OPTION` — a choice from a defined list
+- `RELATION` — a pointer to another record; pair it with `relation_type`
+- `URL` — a link
+- `EMAIL` — an email address
+- `FILE` — a file
+- `FORMULA` — a formula-backed value
+
+A value outside this list is a `400 validation_error`.
+
+
+
+
+
+For a `RELATION` property, what it points at. One of `ISSUE`, `USER`, `RELEASE`, or `RICH_TEXT`. Leave it out
+— or send `null` — for every other property type.
+
+
+
+
+
+Free-form explanation of what the property captures. Nullable.
+
+
+
+
+
+Whether a value must be supplied for this property.
+
+
+
+
+
+Whether the property accepts more than one value.
+
+
+
+
+
+Whether the property is in use. Send `false` to define a property without putting it into circulation yet.
+
+
+
+
+
+The value applied when none is supplied. Send an array even for a single value.
+
+
+
+
+
+Seed the choices for an `OPTION` property in the same call. Write-only: the created options come back on the
+read-only `options` array of the response, and are managed afterwards through
+[Property options](/api-reference/v2/workspace-work-item-property-options/overview), which is also where the
+fields an option accepts are documented.
+
+
+
+
+
+Type-specific configuration. Its shape depends on `property_type`.
+
+
+
+
+
+Type-specific validation configuration.
+
+
+
+
+
+Your system's identifier for this property, for sync and import correlation. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters, nullable.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | --------------------------------------------------------------------------------- |
+| `400` | `validation_error` | Missing `display_name`/`property_type`, or an enum value outside the allowed set. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item properties. |
+| `404` | `resource_not_found` | No such workspace, or it's outside your tenant. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "display_name": "Severity",
+ "property_type": "OPTION",
+ "description": "How badly the customer is affected",
+ "is_required": true,
+ "is_multi": false,
+ "options": [
+ { "name": "Critical", "description": "Production is down" },
+ { "name": "Major", "description": "A core workflow is broken", "is_default": true }
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "display_name": "Severity",
+ "property_type": "OPTION",
+ "description": "How badly the customer is affected",
+ "is_required": True,
+ "is_multi": False,
+ "options": [
+ {"name": "Critical", "description": "Production is down"},
+ {"name": "Major", "description": "A core workflow is broken", "is_default": True},
+ ],
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch("https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/", {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ display_name: "Severity",
+ property_type: "OPTION",
+ description: "How badly the customer is affected",
+ is_required: true,
+ is_multi: false,
+ options: [
+ { name: "Critical", description: "Production is down" },
+ { name: "Major", description: "A core workflow is broken", is_default: true },
+ ],
+ }),
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": [],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/validation-error",
+ "title": "Bad Request",
+ "status": 400,
+ "code": "validation_error",
+ "detail": "The request body failed validation.",
+ "errors": [
+ {
+ "field": "property_type",
+ "message": "\"SELECT\" is not a valid choice."
+ }
+ ]
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-properties/{pk}/
+
+
+
+
+
+Remove a property from the workspace catalog. The delete is soft and the response is `204` with an empty body.
+
+This is the wide blast radius option: the property leaves every project and work item type it reached, unlike
+[detaching it from a single type](/api-reference/v2/workspace-work-item-type-properties/detach-workspace-type-property),
+which only affects that one type.
+
+::: tip Retire before you delete
+If the property has been collecting values, `PATCH` it with `is_active: false` first. The definition stays
+addressable while you migrate, and you can reverse the decision with a single field. Deleting is the move for
+a property created by mistake.
+:::
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Delete the property on the project-level resource instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | -------------------------------------------------------------------------- |
+| `400` | `validation_error` | The request failed validation — most often a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item properties. |
+| `404` | `resource_not_found` | No such workspace or property, or it's outside your tenant. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+```text
+No content
+```
+
+
+
+
+
+```json
+{
+ "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. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/{pk}/
+
+
+
+
+
+Retrieve a single workspace property by id. Use it to read a property's full configuration — its
+`property_type`, whether it is required or multi-valued, and the `options` behind an `OPTION` property —
+before rendering a field or before sending a `PATCH`.
+
+Reads are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes). A property outside your tenant returns `404`,
+never `403` — existence is never leaked.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item properties. |
+| `404` | `resource_not_found` | No such workspace or property, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource-not-found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "No work item property with this id exists in this workspace."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/
+
+
+
+
+
+Return the workspace's custom property catalog as a paginated list. This is how you resolve a property name to
+the `id` you need when creating a context or attaching the property to a work item type, and how you build a
+picker that stays in sync with what the workspace has defined.
+
+The list is the catalog, not what is live: it includes properties that have no
+[context](/api-reference/v2/work-item-property-contexts/overview) yet and therefore do not appear on any work
+item. Reads here are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+This list takes no filters or search term — the whole catalog is returned, page by page. Check your spelling on
+`order_by` and `paginate`: neither is validated, so an unrecognized `order_by` silently falls back to the default
+ordering and anything other than `paginate=cursor` silently uses offset pagination.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `sort_order` , `-sort_order` — the display order Plane uses for the property list. This is the order you
+ want when rendering a form; note that `sort_order` itself is not returned on the property object.
+- `created_at` , `-created_at` — when each property was created
+- `id` , `-id`
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the
+response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead
+of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from
+the response.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item properties. |
+| `404` | `resource_not_found` | No such workspace, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/?order_by=sort_order&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "sort_order", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
+const response = await fetch(`https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/?${params}`, {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "id": "c58b2e94-71a3-4d0f-9e62-4a1c7f38b5d2",
+ "name": "reviewer",
+ "display_name": "Reviewer",
+ "description": "Who signs off before release",
+ "property_type": "RELATION",
+ "relation_type": "USER",
+ "is_required": false,
+ "is_multi": true,
+ "is_active": true,
+ "default_value": [],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:23:12.904551Z"
+ },
+ {
+ "id": "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b",
+ "name": "rollout_date",
+ "display_name": "Rollout date",
+ "description": "When the fix reaches customers",
+ "property_type": "DATETIME",
+ "relation_type": null,
+ "is_required": false,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": [],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:24:03.112884Z"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 3,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+
+
+## The property object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the property. This is the id you use in a context's payload and when attaching the
+ property to a workspace work item type.
+
+- `name` _string_
+
+ Read-only companion to `display_name`. You never set it directly.
+
+- `display_name` _string_
+
+ The label shown wherever the property is rendered. This is the field you write. Maximum 255 characters.
+
+- `description` _string_
+
+ Free-form explanation of what the property captures. May be `null`.
+
+- `property_type` _string_
+
+ What kind of value the property holds. One of `TEXT`, `DATETIME`, `DECIMAL`, `BOOLEAN`, `OPTION`,
+ `RELATION`, `URL`, `EMAIL`, `FILE`, or `FORMULA`. This is the one decision worth getting right up front —
+ it determines what the other fields mean.
+
+- `relation_type` _string_
+
+ For a `RELATION` property, what the property points at. One of `ISSUE`, `USER`, `RELEASE`, or `RICH_TEXT`.
+ `null` for every other property type.
+
+- `is_required` _boolean_
+
+ Whether a value must be supplied for this property.
+
+- `is_multi` _boolean_
+
+ Whether the property accepts more than one value.
+
+- `is_active` _boolean_
+
+ Whether the property is in use. Set it to `false` to retire a property without deleting it.
+
+- `default_value` _array of string_
+
+ The value applied when none is supplied. Always an array, even when `is_multi` is `false`.
+
+- `options` _array of any_
+
+ The choices for an `OPTION` property. Read-only on this object — manage the list through
+ [Property options](/api-reference/v2/workspace-work-item-property-options/overview), or seed it at create
+ time with the write-only `options` body field.
+
+- `settings` _any_
+
+ Type-specific configuration. Its shape depends on `property_type`.
+
+- `validation_rules` _any_
+
+ Type-specific validation configuration.
+
+- `logo_props` _any_
+
+ Presentation data for the property's icon.
+
+- `external_id` , `external_source` _string_
+
+ Correlation fields for sync and import. Together they let you map a property to a field in another system
+ and find it again later. Either may be `null`.
+
+- `created_at` _string (date-time)_
+
+ When the property was created.
+
+
+
+
+
+
+```json
+{
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/work-item-properties/{pk}/
+
+
+
+
+
+Change a workspace property in place. `PATCH` is partial: send only the fields you want to change, and
+everything you omit is left untouched. Omitting a field is not the same as sending `null` — `null` clears a
+nullable field, omission changes nothing.
+
+There is no `PUT` on this resource; sending one returns `405 method_not_allowed`.
+
+Every project and work item type the property reaches sees the change — that is the point of defining it at
+the workspace level.
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Update the property on the project-level resource instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional. The body itself is optional too, though an empty `PATCH` does nothing useful.
+
+
+
+
+
+The label shown wherever the property is rendered. Maximum 255 characters. Renaming is safe for integrations
+that key on `id`.
+
+
+
+
+
+One of `TEXT`, `DATETIME`, `DECIMAL`, `BOOLEAN`, `OPTION`, `RELATION`, `URL`, `EMAIL`, `FILE`, or `FORMULA`.
+Changing the type of a property that is already collecting values reinterprets what those values mean —
+prefer retiring the old property with `is_active: false` and creating a new one.
+
+
+
+
+
+For a `RELATION` property, what it points at. One of `ISSUE`, `USER`, `RELEASE`, or `RICH_TEXT`. Nullable.
+
+
+
+
+
+Free-form explanation of what the property captures. Nullable — send `null` to clear it.
+
+
+
+
+
+Whether a value must be supplied for this property.
+
+
+
+
+
+Whether the property accepts more than one value.
+
+
+
+
+
+Set to `false` to retire the property without deleting it, and back to `true` to bring it into circulation
+again.
+
+
+
+
+
+The value applied when none is supplied. Always an array. Send `[]` to clear it.
+
+
+
+
+
+Write-only. For day-to-day option management — adding one choice, renaming another — use
+[Property options](/api-reference/v2/workspace-work-item-property-options/overview), which addresses each
+option by id.
+
+
+
+
+
+Type-specific configuration. Its shape depends on `property_type`.
+
+
+
+
+
+Type-specific validation configuration.
+
+
+
+
+
+Your system's identifier for this property. Maximum 255 characters, nullable.
+
+
+
+
+
+The system `external_id` came from. Maximum 255 characters, nullable.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | ------------------------------------------------------------------------ |
+| `400` | `validation_error` | An enum value outside the allowed set, or a field over its length limit. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item properties. |
+| `404` | `resource_not_found` | No such workspace or property, or it's outside your tenant. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "display_name": "Customer severity",
+ "is_required": false
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "display_name": "Customer severity",
+ "is_required": False,
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ display_name: "Customer severity",
+ is_required: false,
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Customer severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": false,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "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. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/
+
+
+
+
+
+Add a choice to a workspace-level `OPTION` property. The new option is appended to the end of the property's list and becomes immediately selectable on work items across the workspace.
+
+The property must have `property_type: "OPTION"`. Posting an option to a property of any other type returns `400 validation_error` — the option list is meaningless for a `TEXT` or `DECIMAL` property.
+
+::: warning Workspace mode only
+This write requires the workspace to manage work item types at the workspace level. In project mode it returns `409 work_item_types_managed_at_project` — add the option through the project-level endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level `OPTION` property to add the choice to. A project-scoped property id is a `404` here — this path never crosses into a project. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+The choice as it is displayed. Maximum 255 characters.
+
+
+
+
+
+Free-form text explaining when to pick this choice.
+
+
+
+
+
+Make this the property's default choice. At most one option per property can be the default, and there is no automatic hand-off: if another option already has it, this request is rejected with `400 validation_error`. Clear the current default with a `PATCH` first.
+
+
+
+
+
+Your system's identifier for this option, for sync and import correlation. Maximum 255 characters.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+`sort_order` is not accepted. Plane appends the new option after the current last one, so create options in the order you want them displayed.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400` | `validation_error` | Missing `name`, a field over 255 characters, `is_default` when the property already has a default, or a property whose `property_type` is not `OPTION`. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write this workspace's properties. |
+| `404` | `resource_not_found` | No such workspace or workspace-level property, or it's outside your tenant. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. Use the project-level options endpoint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Sandbox",
+ "description": "Reported on an isolated test tenant",
+ "external_id": "env-sandbox",
+ "external_source": "servicedesk"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Sandbox",
+ "description": "Reported on an isolated test tenant",
+ "external_id": "env-sandbox",
+ "external_source": "servicedesk",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Sandbox",
+ description: "Reported on an isolated test tenant",
+ external_id: "env-sandbox",
+ external_source: "servicedesk",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26",
+ "name": "Sandbox",
+ "description": "Reported on an isolated test tenant",
+ "is_default": false,
+ "sort_order": 40000,
+ "external_id": "env-sandbox",
+ "external_source": "servicedesk"
+}
+```
+
+
+
+
+
+```json
+{
+ "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."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/{pk}/
+
+
+
+
+
+Remove a choice from a workspace-level `OPTION` property. The delete is soft — the option stops being selectable and disappears from reads, and the request returns `204` with an empty body.
+
+Deleting an option is not the same as renaming it. If the choice is being reworded, `PATCH` it instead: [Update a workspace property option](/api-reference/v2/workspace-work-item-property-options/update-workspace-property-option) keeps the option's `id`, so work items already holding it keep their value.
+
+::: warning Workspace mode only
+This write requires the workspace to manage work item types at the workspace level. In project mode it returns `409 work_item_types_managed_at_project` — delete the option through the project-level endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property the option belongs to. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+The option to delete. It is looked up within the property, so an option id under the wrong `property_id` is a `404`.
+
+
+
+
+
+Deleting the property's default option leaves the property with no default. Nothing promotes another option in its place — set a new default explicitly if the property needs one.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write this workspace's properties. |
+| `404` | `resource_not_found` | No such workspace, workspace-level property, or option — or it's outside your tenant. Already-deleted options are `404` too. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. Use the project-level options endpoint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+(empty body)
+```
+
+
+
+
+
+```json
+{
+ "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."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/{pk}/
+
+
+
+
+
+Retrieve one option on a workspace-level `OPTION` property. Use it to resolve a stored option id back to a display name, or to confirm an option still exists before writing it onto a work item.
+
+Reads work in either work item type mode — only writes are mode-gated. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property the option belongs to. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+The option to retrieve.
+
+
+
+
+
+The option is looked up within the property, so a valid option id under the wrong `property_id` is a `404` rather than a match. Deleted options are gone from this endpoint too — a soft-deleted option returns `404`.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ------------------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's properties. |
+| `404` | `resource_not_found` | No such workspace, workspace-level property, or option — or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource_not_found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "The requested resource was not found."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/
+
+
+
+
+
+Return the selectable choices on a workspace-level `OPTION` property as a paginated list. This is how you resolve an option name to the `id` you store when setting the property on a work item, and how you build a picker that stays in sync with the property definition.
+
+Results are ordered by `sort_order` by default, which is the order the option list is meant to be displayed in.
+
+Reads work in either work item type mode. Only writes are mode-gated — see [Work item type modes](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property whose options you want — see [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+This endpoint filters options by property rather than looking the property up, so an id that isn't a workspace-level property in this workspace — including a project-scoped property id — comes back as an empty list, not a `404`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+There are no filters on this resource. A property's option list is small and self-contained, so fetch it whole and match on `id` in your own code.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `sort_order` , `-sort_order` — the property's own display order. This is the default.
+- `created_at` , `-created_at` — when each option was added
+- `id` , `-id`
+
+A value outside this list is ignored and the default `sort_order` ordering is used, so a typo shows up as an unexpected order rather than an error.
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most properties have fewer than 20 options, so one page is usually the whole list.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead of `next` and `total_count`. Omit it for the default offset envelope.
+
+Cursor pagination needs a unique, monotonic sort key, and `sort_order` is neither. Pair it with `order_by=created_at` or `order_by=id`; a bare `?paginate=cursor` falls back to the default `sort_order` ordering and is rejected with `ordering_not_cursor_eligible`.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from the response.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ---------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's properties. |
+| `404` | `resource_not_found` | No such workspace, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/?order_by=sort_order&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "sort_order", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57",
+ "name": "Staging",
+ "description": "Reported on the shared pre-release environment",
+ "is_default": false,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "a17f3c95-2d64-4b08-8e51-c94b7d60f382",
+ "name": "Development",
+ "description": "Reported on a local or branch environment",
+ "is_default": false,
+ "sort_order": 30000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 3,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+
+
+## The property option object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the option. This is the value you store when you set the property on a work item, so treat it as the stable handle — `name` is only a label.
+
+- `name` _string_
+
+ The choice as it is displayed. Maximum 255 characters.
+
+- `description` _string_
+
+ Free-form text explaining when to pick this choice.
+
+- `is_default` _boolean_
+
+ Whether this is the property's default choice. At most one option per property can carry it.
+
+- `sort_order` _number_
+
+ Position of the option within the property's list. Lower values come first, and this is the order the list endpoint returns by default. Assigned by Plane — it is not a writable field.
+
+- `external_id` , `external_source` _string_
+
+ Correlation fields for sync and import. Together they let you map an option to a record in another system and find it again later.
+
+::: tip Store the id, not the name
+Renaming an option keeps its `id`, so integrations that matched on `id` keep working and integrations that matched on `name` break. Resolve names to ids once, then reference ids.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "c31a7e04-5f6b-4d29-8a13-7e0c2b9f4a65",
+ "name": "Production",
+ "description": "Reported on live customer traffic",
+ "is_default": true,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/work-item-properties/{property_id}/options/{pk}/
+
+
+
+
+
+Change one option on a workspace-level `OPTION` property — rename it, reword its description, or move the property's default onto it.
+
+The update is partial: fields you omit are left untouched, and omitting a field is not the same as sending `null`. Renaming an option keeps its `id`, so every work item already holding the option keeps its value.
+
+::: warning Workspace mode only
+This write requires the workspace to manage work item types at the workspace level. In project mode it returns `409 work_item_types_managed_at_project` — update the option through the project-level endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The workspace-level property the option belongs to. See [Workspace work item properties](/api-reference/v2/workspace-work-item-properties/overview).
+
+
+
+
+
+The option to update. It is looked up within the property, so an option id under the wrong `property_id` is a `404`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional. Send only what you are changing.
+
+
+
+
+
+The choice as it is displayed. Maximum 255 characters.
+
+
+
+
+
+Free-form text explaining when to pick this choice.
+
+
+
+
+
+Make this the property's default choice, or send `false` to clear it. At most one option per property can be the default: setting it while a different option already holds it returns `400 validation_error`, so clear the current default first and then set the new one.
+
+
+
+
+
+Your system's identifier for this option, for sync and import correlation. Maximum 255 characters.
+
+
+
+
+
+The system `external_id` came from, for example `github` or `jira`. Maximum 255 characters.
+
+
+
+
+
+`sort_order` is not accepted here — an option's position is fixed at creation time and cannot be moved through the API.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_properties:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `400` | `validation_error` | A field over 255 characters, or `is_default: true` when another option on the property is already the default. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write this workspace's properties. |
+| `404` | `resource_not_found` | No such workspace, workspace-level property, or option — or it's outside your tenant. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. Use the project-level options endpoint. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Pre-production",
+ "description": "Reported on the shared pre-release environment"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Pre-production",
+ "description": "Reported on the shared pre-release environment",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Pre-production",
+ description: "Reported on the shared pre-release environment",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "5e8b7d21-4a09-4c63-b7f2-90d1c3a86e57",
+ "name": "Pre-production",
+ "description": "Reported on the shared pre-release environment",
+ "is_default": false,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/validation_error",
+ "title": "Validation Error",
+ "status": 400,
+ "code": "validation_error",
+ "detail": "Only one option can be the default."
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/
+
+
+
+
+
+Attach one or more **existing** workspace properties to a workspace-level work item type. This does not create
+properties — create those first with
+[Create a workspace property](/api-reference/v2/workspace-work-item-properties/create-workspace-work-item-property),
+then send their ids here.
+
+Because the same property can be attached to many types, this is how you reuse one `Severity` definition
+across `Bug`, `Incident`, and `Escalation` instead of maintaining three near-identical fields.
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Attach through the project-level route instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type to attach the properties to.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Ids of properties to attach, taken from the workspace property catalog. Send the whole set you want in one
+call rather than one request per property.
+
+Every id must already exist in this workspace. An unknown id — including one that belongs to another workspace
+— fails the request with `400 validation_error`; nothing is attached, and a cross-tenant id is never silently
+linked.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | ----------------------------------------------------------------------------- |
+| `400` | `validation_error` | `properties` missing, not an array, or holding an id that doesn't exist here. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item types. |
+| `404` | `resource_not_found` | No such workspace or type, or it's outside your tenant. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "properties": [
+ "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b"
+ ]
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "properties": [
+ "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b",
+ ]
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ properties: ["a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15", "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b"],
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "properties": ["a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15", "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b"]
+}
+```
+
+
+
+
+
+```json
+{
+ "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. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/{pk}/
+
+
+
+
+
+Remove a property from a workspace-level work item type. The type stops carrying the property; nothing else
+changes.
+
+::: info Detaching is not deleting
+The property stays in the workspace catalog and stays attached to every other type that uses it. To remove it
+from the workspace entirely, call
+[Delete a workspace property](/api-reference/v2/workspace-work-item-properties/delete-workspace-work-item-property)
+instead.
+:::
+
+::: warning Wrong mode is a 409, not a 404
+If the workspace manages work item types at the **project** level, this route returns `409` with the code
+`work_item_types_managed_at_project`. Detach through the project-level route instead. See
+[Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type to detach the property from.
+
+
+
+
+
+The property's id. A property that is not attached to this type returns `404`.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | -------------------------------------------------------------------------- |
+| `400` | `validation_error` | The request failed validation — most often a `pk` that isn't a valid UUID. |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't write workspace work item types. |
+| `404` | `resource_not_found` | No such workspace, type, or property — or the property isn't on this type. |
+| `409` | `work_item_types_managed_at_project` | This workspace manages work item types at the project level. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code)
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status);
+```
+
+
+
+
+
+
+```text
+No content
+```
+
+
+
+
+
+```json
+{
+ "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. Use the project-level endpoint instead."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/{pk}/
+
+
+
+
+
+Retrieve one property as it is attached to a workspace-level work item type. Use it to read a single
+property's configuration — its `property_type`, whether it is required, its options — without pulling the
+whole list.
+
+This route also answers the membership question: a `200` means the property is attached to this type, and a
+`404` means it is not. A property that exists in the workspace but is not on this type returns `404`, the same
+as an id that does not exist at all.
+
+Reads are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes).
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type the property is attached to.
+
+
+
+
+
+The property's id.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | -------------------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item types. |
+| `404` | `resource_not_found` | No such workspace, type, or property — or the property isn't on this type. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource-not-found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "No property with this id is attached to this work item type."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/{type_id}/properties/
+
+
+
+
+
+Return the custom properties attached to one workspace-level work item type, as a paginated list. Reach for it
+when you are building a form for that type, or checking what a type already carries before attaching more.
+
+Reads are unaffected by the workspace's
+[work item type mode](/api-reference/v2/work-item-type-modes) — this route answers even when the workspace
+manages types at the project level.
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is
+`my-team`.
+
+
+
+
+
+The workspace work item type whose properties you want. Get it from
+[List workspace work item types](/api-reference/v2/workspace-work-item-types/list-workspace-work-item-types).
+
+
+
+
+
+
+
+
+### Query Parameters
+
+This list takes no filters or search term — a type's property set is small and returned whole. Check your spelling on
+`order_by` and `paginate`: neither is validated, so an unrecognized `order_by` silently falls back to the default
+ordering and anything other than `paginate=cursor` silently uses offset pagination.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `sort_order` , `-sort_order` — the display order Plane uses for the property list. This is the order you
+ want when rendering a form; note that `sort_order` itself is not returned on the property object.
+- `created_at` , `-created_at` — when each property was created
+- `id` , `-id`
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most types carry fewer than 20 properties, so one page is usually the
+whole set.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the
+response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead
+of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from
+the response.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | -------------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read workspace work item types. |
+| `404` | `resource_not_found` | No such workspace or type, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/?order_by=sort_order&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "sort_order", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
+const response = await fetch(
+ `https://api.plane.so/api/v2/workspaces/my-team/work-item-types/d1a0b7c6-2f83-4e19-9a55-3b6c8d0e4f27/properties/?${params}`,
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "id": "3fb6c0d8-4e21-49a7-b5c3-90ad72e14f6b",
+ "name": "rollout_date",
+ "display_name": "Rollout date",
+ "description": "When the fix reaches customers",
+ "property_type": "DATETIME",
+ "relation_type": null,
+ "is_required": false,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": [],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:24:03.112884Z"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 2,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+
+
+## The property object
+
+Reads on this resource return the full property object, the same shape the workspace property catalog returns.
+Every field is read-only here — this route only changes which properties a type carries, never what a property
+is.
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the property. This is the id you send in `properties` to attach it, and the `pk` you
+ use to detach it.
+
+- `name` _string_
+
+ Read-only companion to `display_name`. You never set it directly.
+
+- `display_name` _string_
+
+ The label shown wherever the property is rendered.
+
+- `description` _string_
+
+ Free-form explanation of what the property captures. May be `null`.
+
+- `property_type` _string_
+
+ What kind of value the property holds. One of `TEXT`, `DATETIME`, `DECIMAL`, `BOOLEAN`, `OPTION`,
+ `RELATION`, `URL`, `EMAIL`, `FILE`, or `FORMULA`.
+
+- `relation_type` _string_
+
+ For a `RELATION` property, what it points at — one of `ISSUE`, `USER`, `RELEASE`, or `RICH_TEXT`. `null` for
+ every other property type.
+
+- `is_required` _boolean_
+
+ Whether a value must be supplied for this property.
+
+- `is_multi` _boolean_
+
+ Whether the property accepts more than one value.
+
+- `is_active` _boolean_
+
+ Whether the property is in use. A property can be retired by setting this to `false` on the catalog
+ resource, without deleting it.
+
+- `default_value` _array of string_
+
+ The value applied when none is supplied. Always an array, even when `is_multi` is `false`.
+
+- `options` _array of any_
+
+ The choices for an `OPTION` property. Manage them through
+ [Property options](/api-reference/v2/workspace-work-item-property-options/overview).
+
+- `settings` _any_
+
+ Type-specific configuration. Its shape depends on `property_type`.
+
+- `validation_rules` _any_
+
+ Type-specific validation configuration.
+
+- `logo_props` _any_
+
+ Presentation data for the property's icon.
+
+- `external_id` , `external_source` _string_
+
+ Correlation fields for sync and import. Together they let you map a property to a record in another system
+ and find it again later. Either may be `null`.
+
+- `created_at` _string (date-time)_
+
+ When the property was created.
+
+::: tip There is no separate link object
+The response is the property, not a join record. If you need to know whether a given property is on a type,
+`GET …/properties/{pk}/` — a `404` means it is not attached, and a `200` means it is.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "a7e3f1d0-5c92-4b68-8f31-2d4a6b9e0c15",
+ "name": "severity",
+ "display_name": "Severity",
+ "description": "How badly the customer is affected",
+ "property_type": "OPTION",
+ "relation_type": null,
+ "is_required": true,
+ "is_multi": false,
+ "is_active": true,
+ "default_value": ["Major"],
+ "options": [
+ {
+ "id": "9d2c7b41-6a80-4f35-8e19-5c3b0a7d2e46",
+ "name": "Critical",
+ "description": "Production is down",
+ "is_default": false,
+ "sort_order": 10000,
+ "external_id": null,
+ "external_source": null
+ },
+ {
+ "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
+ "name": "Major",
+ "description": "A core workflow is broken",
+ "is_default": true,
+ "sort_order": 20000,
+ "external_id": null,
+ "external_source": null
+ }
+ ],
+ "settings": {},
+ "validation_rules": {},
+ "logo_props": {},
+ "external_id": null,
+ "external_source": null,
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ 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.
+
+::: warning 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](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+
+
+
+
+Display name for the type, for example `Incident`. Maximum 255 characters. Reusing a name that already exists in the workspace returns `409`.
+
+
+
+
+
+What this type is for. It is shown next to the type wherever someone picks it, so write it for the person choosing.
+
+
+
+
+
+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.
+
+
+
+
+
+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`.
+
+
+
+
+
+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](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type).
+
+
+
+
+
+### 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. |
+
+
+
+
+
+
+
+
+
+
+```bash
+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"
+}'
+```
+
+
+
+
+```python
+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())
+```
+
+
+
+
+```javascript
+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();
+```
+
+
+
+
+
+
+```json
+{
+ "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"
+}
+```
+
+
+
+
+
+```json
+{
+ "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."
+}
+```
+
+
+
+
+
+ DELETE
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/
+
+
+
+
+
+Remove a work item type from the workspace. Because the type is shared, the removal is felt by every project working from the workspace list — check what still uses it before you call this.
+
+A successful delete returns `204` with an empty body. There is nothing to parse; branch on the status code.
+
+::: warning 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`. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to delete.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | -------------------------------------------------------------------------------- |
+| `400` | `validation_error` | The request can't be processed as sent. 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 type or 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 deleted in its current state — the response `detail` says why. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: info A repeat delete returns 404
+Delete is not idempotent in its response: the second call for the same id returns `404 resource_not_found`, because the type is already gone. Treat `404` on retry as success rather than as an error worth alerting on.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X DELETE \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/a3f52d07-8e19-4c6b-92d4-0b7e15c8f326/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.delete(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/a3f52d07-8e19-4c6b-92d4-0b7e15c8f326/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.status_code) # 204
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/a3f52d07-8e19-4c6b-92d4-0b7e15c8f326/",
+ {
+ method: "DELETE",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+console.log(response.status); // 204
+```
+
+
+
+
+
+
+```text
+No content
+```
+
+
+
+
+
+```json
+{
+ "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. Delete the type on the project's work item types endpoint."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/
+
+
+
+
+
+Retrieve one workspace-level type by id. Reach for this when you already hold a type id — from a work item's `type_id`, a webhook payload, or a stored mapping — and need its current name, description, or active flag.
+
+::: info Reads work in either mode
+Retrieval is unaffected by [work item type modes](/api-reference/v2/work-item-type-modes). A workspace type stays readable here even when the workspace manages types at the project level; only writes are mode-gated.
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to retrieve. A project-level type id returns `404` here — this endpoint only resolves types defined on the workspace.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ----------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's types. |
+| `404` | `resource_not_found` | No such type or workspace, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+::: info No expansion, and no external ids
+Work item types don't accept `?expand=` — the response is the flat object shown here. `external_id` and `external_source` are write-only and never come back, so resolve a type by the Plane `id` you stored at create time.
+:::
+
+::: info Existence is never leaked
+A type outside your tenant returns `404`, not `403`. If a cached id starts returning `404`, re-read the workspace's set with [List workspace work item types](/api-reference/v2/workspace-work-item-types/list-workspace-work-item-types) rather than retrying.
+:::
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "type": "https://api.plane.so/errors/resource-not-found",
+ "title": "Not Found",
+ "status": 404,
+ "code": "resource_not_found",
+ "detail": "No Issue Type matches the given query."
+}
+```
+
+
+
+
+
+ GET
+ /api/v2/workspaces/{slug}/work-item-types/
+
+
+
+
+
+Return the workspace's work item types as a paginated list. This is where you resolve a type name such as `Bug` to the `id` you need — to set `type_id` on a work item, to attach properties to the type, or to hand to a project [import](/api-reference/v2/work-item-types/import-work-item-types).
+
+There is no project segment in the path: these are the types defined once for the whole workspace.
+
+::: info Reads work in either mode
+Listing is unaffected by [work item type modes](/api-reference/v2/work-item-type-modes). You can read the workspace list even while the workspace manages types at the project level — only writes are mode-gated.
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+
+
+
+### Query Parameters
+
+This endpoint takes ordering and pagination only — there are no filter or search parameters. A workspace's type list is short by design, so read a page and match on `name` or `id` in your own code.
+
+
+
+
+
+### Ordering
+
+
+
+
+
+Field to sort by. Prefix with `-` for descending.
+
+- `name` , `-name` — alphabetical, which is what you usually want for a picker
+- `level` , `-level` — the type's level in the work item hierarchy
+- `created_at` , `-created_at` — when each type was added
+- `id` , `-id`
+
+A value outside this list is not rejected — it quietly falls back to the default ordering. Check your spelling: a typo surfaces as a differently-sorted page, not as an error.
+
+
+
+
+
+
+
+
+### Pagination
+
+
+
+
+
+Page size. Defaults to 50, maximum 200. Most workspaces define fewer than 20 types, so one page is usually the whole set.
+
+
+
+
+
+Number of rows to skip from the start of the result set. Maximum 10000. Read the `next` value from the response rather than computing offsets yourself.
+
+
+
+
+
+Set to `cursor` to opt into the COUNT-free keyset envelope, which returns `next_cursor` and `has_more` instead of `next` and `total_count`. Omit it for the default offset envelope.
+
+
+
+
+
+Defaults to `true`. Set to `false` to skip the `COUNT(*)` behind `total_count`; the field is then omitted from the response.
+
+
+
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:read`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | -------------------- | ----------------------------------------------------------- |
+| `401` | `unauthorized` | Missing or invalid credentials. |
+| `403` | `forbidden` | Your role or token scope can't read this workspace's types. |
+| `404` | `resource_not_found` | No such workspace, or it's outside your tenant. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X GET \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/?order_by=name&per_page=50" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.get(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/",
+ headers={"X-Api-Key": "your-api-key"},
+ params={"order_by": "name", "per_page": 50},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const params = new URLSearchParams({ order_by: "name", per_page: "50" });
+const response = await fetch(`https://api.plane.so/api/v2/workspaces/my-team/work-item-types/?${params}`, {
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+});
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ },
+ {
+ "id": "5e8b0c19-7a4d-42f6-9b83-1c0d6e2f7a45",
+ "name": "Epic",
+ "description": "A large body of work spanning several work items",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": true,
+ "level": 1,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.512907Z"
+ },
+ {
+ "id": "9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914",
+ "name": "Task",
+ "description": "Standard unit of work",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.548221Z"
+ }
+ ],
+ "next": null,
+ "previous": null,
+ "total_count": 3,
+ "pagination": {
+ "style": "offset"
+ }
+}
+```
+
+
+
+
+
+```json
+{
+ "data": [
+ {
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+ }
+ ],
+ "next_cursor": "b3A9MTcx",
+ "has_more": true,
+ "pagination": {
+ "style": "cursor"
+ }
+}
+```
+
+
+
+
+
+ POST
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/mark-default/
+
+
+
+
+
+Promote a type to the workspace default — the type a work item gets when none is supplied. Exactly one type holds the flag, so marking this one clears it on the type that held it before.
+
+`is_default` is read-only on create and update, which is why this is its own call. **Send no body.**
+
+::: warning 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` — set the default on the project endpoint instead. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to make the default.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+None. The type is identified entirely by `pk`; send an empty request.
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | --------------------------------------------------------------------------------- |
+| `400` | `validation_error` | The type can't be made default as requested. 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 type or 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 default can't be moved in the current state — the response `detail` says why. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X POST \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914/mark-default/" \
+ -H "X-Api-Key: $PLANE_API_KEY"
+```
+
+
+
+
+```python
+import requests
+
+response = requests.post(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914/mark-default/",
+ headers={"X-Api-Key": "your-api-key"},
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914/mark-default/",
+ {
+ method: "POST",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ },
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "9d2f1b73-4c85-4a06-b3e1-7f8c25a0d914",
+ "name": "Task",
+ "description": "Standard unit of work",
+ "is_active": true,
+ "is_default": true,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.548221Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "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. Mark the default on the project's work item types endpoint."
+}
+```
+
+
+
+
+
+
+
+## The work item type object
+
+### Attributes
+
+- `id` _string (uuid)_
+
+ Unique identifier for the type. This is the id you send as `type_id` on a work item, and the id you pass when importing types into a project.
+
+- `name` _string_
+
+ Display name, for example `Bug`. Maximum 255 characters.
+
+- `description` _string_
+
+ What this type is for. Shown next to the type wherever it is picked in Plane, so it is worth writing for the people choosing, not for your integration.
+
+- `is_active` _boolean_
+
+ Whether the type can currently be selected. Deactivating a type retires it from pickers without deleting it or touching the work items already using it.
+
+- `is_default` _boolean_
+
+ Whether this is the workspace's default type. Read-only on create and update — change it with [Mark a type as default](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type).
+
+- `is_epic` _boolean_
+
+ Whether the type is an epic type. Read-only, and there is no body parameter for it: every type you create through this API is a standard work item type.
+
+- `level` _number_
+
+ The type's level in the work item hierarchy. Read-only, and one of the values you can sort by with `order_by`.
+
+- `logo_props` _any_
+
+ Free-form icon metadata Plane uses to render the type's badge. Managed in the app — read-only over the API.
+
+- `created_at` _string (date-time)_
+
+ When the type was created.
+
+::: info `external_id` is write-only
+You can send `external_id` and `external_source` when creating or updating a type so an import can correlate it with a record in your own system, but neither field comes back on read. Keep your own mapping from your id to the Plane `id`.
+:::
+
+
+
+
+
+
+```json
+{
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Bug",
+ "description": "Something is broken and needs a fix",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+ PATCH
+ /api/v2/workspaces/{slug}/work-item-types/{pk}/
+
+
+
+
+
+Rename a type, rewrite its description, or retire it with `is_active: false`. The edit lands once and every project working from the workspace list sees it — that is the point of managing types at the workspace level.
+
+The update is partial: omitted fields are left untouched, and omitting a field is not the same as sending `null`. There is no `PUT`.
+
+::: warning 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`. See [Work item type modes](/api-reference/v2/work-item-type-modes).
+:::
+
+
+
+### Path Parameters
+
+
+
+
+
+The workspace slug. It appears in your Plane URLs — in `https://app.plane.so/my-team/projects/`, the slug is `my-team`.
+
+
+
+
+
+The id of the work item type to update.
+
+
+
+
+
+
+
+
+### Body Parameters
+
+Every field is optional — send only what changes.
+
+
+
+
+
+New display name. Maximum 255 characters. Renaming is safe for integrations that key on `id`; anything matching on the old name breaks, which is a reason to key on `id`.
+
+
+
+
+
+New description of what the type is for.
+
+
+
+
+
+Send `false` to retire the type from pickers without deleting it — work items already classified with it keep their type. Send `true` to bring it back.
+
+
+
+
+
+Your system's identifier for this type. Maximum 255 characters. Send `null` to clear it. Write-only — it is not returned on read.
+
+
+
+
+
+The system `external_id` came from, for example `jira`. Maximum 255 characters. Send `null` to clear it. Write-only, like `external_id`.
+
+
+
+
+
+`is_default`, `is_epic`, `level`, and `logo_props` are read-only — sending them has no effect. To change which type is the default, call [Mark a type as default](/api-reference/v2/workspace-work-item-types/mark-default-workspace-work-item-type).
+
+
+
+
+
+### Scopes
+
+`workspaces.work_item_types:write`
+
+
+
+
+
+### Errors
+
+| Status | Code | Cause |
+| ------ | ------------------------------------ | ---------------------------------------------------------------------------- |
+| `400` | `validation_error` | An invalid value — for example a `name` over 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 type or 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 change collides with another type — most often a name already in use. |
+| `429` | `rate_limited` | Throttled. Honor the `Retry-After` header before retrying. |
+
+
+
+
+
+
+
+
+
+
+```bash
+curl -X PATCH \
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/" \
+ -H "X-Api-Key: $PLANE_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "name": "Defect",
+ "description": "A confirmed break in shipped behavior"
+}'
+```
+
+
+
+
+```python
+import requests
+
+response = requests.patch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ headers={"X-Api-Key": "your-api-key"},
+ json={
+ "name": "Defect",
+ "description": "A confirmed break in shipped behavior",
+ },
+)
+print(response.json())
+```
+
+
+
+
+```javascript
+const response = await fetch(
+ "https://api.plane.so/api/v2/workspaces/my-team/work-item-types/c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63/",
+ {
+ method: "PATCH",
+ headers: {
+ "X-Api-Key": "your-api-key",
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({
+ name: "Defect",
+ description: "A confirmed break in shipped behavior",
+ }),
+ }
+);
+const data = await response.json();
+```
+
+
+
+
+
+
+```json
+{
+ "id": "c1a7d3f4-6b28-4e90-8d15-2f7a0b9c4e63",
+ "name": "Defect",
+ "description": "A confirmed break in shipped behavior",
+ "is_active": true,
+ "is_default": false,
+ "is_epic": false,
+ "level": 0,
+ "logo_props": {},
+ "created_at": "2026-01-14T09:22:41.478363Z"
+}
+```
+
+
+
+
+
+```json
+{
+ "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. Update the type on the project's work item types endpoint."
+}
+```
+
+
+
+
+
@@ -31,7 +31,7 @@ Deploy Plane on your infrastructure with Docker, Kubernetes, or other methods. C
-
+
180+ endpoints to manage projects, work items, cycles, modules, and more.
diff --git a/vercel.json b/vercel.json
index f1bdea82..24ff4e09 100644
--- a/vercel.json
+++ b/vercel.json
@@ -6,7 +6,7 @@
"headers": [
{
"key": "Link",
- "value": "; rel=\"describedby\"; type=\"text/plain\", ; rel=\"service-doc\"; type=\"text/html\", ; rel=\"sitemap\"; type=\"application/xml\""
+ "value": "; rel=\"describedby\"; type=\"text/plain\", ; rel=\"service-doc\"; type=\"text/html\", ; rel=\"sitemap\"; type=\"application/xml\""
},
{
"key": "X-Robots-Tag",
@@ -18,7 +18,11 @@
"redirects": [
{
"source": "/api-reference",
- "destination": "/api-reference/introduction"
+ "destination": "/api-reference/v2/introduction"
+ },
+ {
+ "source": "/api-reference/introduction",
+ "destination": "/api-reference/v2/introduction"
},
{
"source": "/api-reference/byoa/build-plane-app",
@@ -30,35 +34,39 @@
},
{
"source": "/api-reference/cycle-issue/overview",
- "destination": "/api-reference/cycle/overview"
+ "destination": "/api-reference/v1/cycle/overview"
},
{
"source": "/api-reference/cycle-issue/add-cycle-issue",
- "destination": "/api-reference/cycle/add-cycle-work-items"
+ "destination": "/api-reference/v1/cycle/add-cycle-work-items"
},
{
"source": "/api-reference/cycle-issue/list-cycle-issues",
- "destination": "/api-reference/cycle/list-cycle-work-items"
+ "destination": "/api-reference/v1/cycle/list-cycle-work-items"
},
{
"source": "/api-reference/cycle-issue/delete-cycle-issue",
- "destination": "/api-reference/cycle/remove-cycle-work-item"
+ "destination": "/api-reference/v1/cycle/remove-cycle-work-item"
},
{
"source": "/api-reference/module-issue/overview",
- "destination": "/api-reference/module/overview"
+ "destination": "/api-reference/v1/module/overview"
},
{
"source": "/api-reference/module-issue/add-module-issue",
- "destination": "/api-reference/module/add-module-work-items"
+ "destination": "/api-reference/v1/module/add-module-work-items"
},
{
"source": "/api-reference/module-issue/list-module-issues",
- "destination": "/api-reference/module/list-module-work-items"
+ "destination": "/api-reference/v1/module/list-module-work-items"
},
{
"source": "/api-reference/module-issue/delete-module-issue",
- "destination": "/api-reference/module/remove-module-work-item"
+ "destination": "/api-reference/v1/module/remove-module-work-item"
+ },
+ {
+ "source": "/api-reference/:path((?!v1/|v2/).*)",
+ "destination": "/api-reference/v1/:path"
},
{
"source": "/plane-one/governance/authentication/custom-sso",