Update a workspace work item property

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.

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.

Path Parameters

slug:requiredstring

The workspace slug. It appears in your Plane URLs — in https://app.plane.so/my-team/projects/, the slug is my-team.

pk:requiredstring (uuid)

The property's id.

Body Parameters

Every field is optional. The body itself is optional too, though an empty PATCH does nothing useful.

display_name:optionalstring

The label shown wherever the property is rendered. Maximum 255 characters. Renaming is safe for integrations that key on id.

property_type:optionalstring

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.

relation_type:optionalstring

For a RELATION property, what it points at. One of ISSUE, USER, RELEASE, or RICH_TEXT. Nullable.

description:optionalstring

Free-form explanation of what the property captures. Nullable — send null to clear it.

is_required:optionalboolean

Whether a value must be supplied for this property.

is_multi:optionalboolean

Whether the property accepts more than one value.

is_active:optionalboolean

Set to false to retire the property without deleting it, and back to true to bring it into circulation again.

default_value:optionalarray of string

The value applied when none is supplied. Always an array. Send [] to clear it.

options:optionalarray of object

Write-only. For day-to-day option management — adding one choice, renaming another — use Property options, which addresses each option by id.

settings:optionalany

Type-specific configuration. Its shape depends on property_type.

validation_rules:optionalany

Type-specific validation configuration.

external_id:optionalstring

Your system's identifier for this property. Maximum 255 characters, nullable.

external_source:optionalstring

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.

Update a workspace property

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
}'

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())

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();

Response200

{
  "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"
}

Response409

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

Scoping is edited elsewhere

PATCH here changes the property's definition, not where it applies. To narrow or widen the projects and work item types that see it, update its property contexts instead.