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, and 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, which is the purpose of defining it at the workspace level.

Wrong mode returns 409, not 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 changes nothing.

display_name:optionalstring

The label shown wherever the property is rendered. Maximum 255 characters. Renaming is safe for integrations that match 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. Retire the old property with is_active: false and create a new one instead.

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 put it back into use.

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, such as adding one choice or 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.

Response shaping

fields:optionalstring

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

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

Requestable here: created_at, default_value, description, display_name, external_id, external_source, id, is_active, is_multi, is_required, logo_props, name, options, property_type, relation_type, settings, updated_at, updated_by_id, validation_rules.

See Sparse fields.

Scopes

workspaces.work_item_properties:write

Errors

Status	Code	Cause
400	invalid_request	An enum value outside the allowed set, or a field over its length limit.
401	unauthorized	Missing or invalid credentials.
402	payment_required	The feature this endpoint belongs to isn't enabled on your plan, or is switched off.
403	forbidden	Your role or token scope can't write workspace work item properties.
404	not_found	No such workspace or property, or it's outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	conflict	This workspace manages work item types at the project level.
413	payload_too_large	The request body is over the size limit.
415	unsupported_media_type	The Content-Type isn't one this endpoint accepts.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

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",
      "parent_id": null,
      "is_default": false,
      "is_active": true,
      "sort_order": 10000,
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "updated_at": "2026-02-03T16:45:12.904117Z",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    },
    {
      "id": "5a83e0b7-2c46-4d19-9f70-6b12c8e5a03d",
      "name": "Major",
      "description": "A core workflow is broken",
      "parent_id": null,
      "is_default": true,
      "is_active": true,
      "sort_order": 20000,
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "updated_at": "2026-02-03T16:45:12.904117Z",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    }
  ],
  "settings": {},
  "validation_rules": {},
  "logo_props": {},
  "external_id": null,
  "external_source": null,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-02-03T16:45:12.904117Z",
  "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
}

Response409

{
  "type": "conflict",
  "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.