Update a property option

PATCH/api/v2/workspaces/{slug}/projects/{project_id}/work-item-properties/{property_id}/options/{pk}/

Change an option's label, description, default flag, or correlation fields. Work items that already hold this option keep holding it — they store the option's id, so a rename is purely cosmetic and no stored value changes.

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.

Path Parameters

slug:requiredstring

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

project_id:requiredstring (uuid)

The project that owns the property.

property_id:requiredstring (uuid)

The OPTION property the option belongs to. See Work item properties.

pk:requiredstring (uuid)

The id of the option to update. An option id that belongs to a different property returns 404.

Body Parameters

Every field is optional — send the subset you are changing.

name:optionalstring

New label for the option. Maximum 255 characters. Safe to change at any time: values on work items reference the option id, not its name.

description:optionalstring

Free-form explanation of what the option means.

is_default:optionalboolean

Whether this option is preselected when a work item is created without an explicit value for the property. Changing it affects only work items created from now on — existing values are untouched.

external_id:optionalstring

Your system's identifier for this option, for sync and import correlation. Maximum 255 characters. Nullable.

external_source:optionalstring

The system external_id came from, for example github or jira. Maximum 255 characters. Nullable.

sort_order is not writable

sort_order is returned on every read but is not accepted in the request body. There is no PATCH that repositions an option — Plane maintains the ordering weight itself.

Scopes

projects.work_item_properties:write

Errors

Status	Code	Cause
400	validation_error	A field over its 255-character limit, or a value of the wrong type.
401	unauthorized	Missing or invalid credentials.
403	forbidden	Your role or token scope can't write this project's properties.
404	resource_not_found	No such option, property, project, or workspace — or the option belongs to a different property.
409	work_item_types_managed_at_workspace	The workspace manages work item types at the workspace level, so this project-level write is rejected.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Wrong mode is a 409, not a 404

If the workspace manages work item types at the workspace level, this project-level PATCH returns 409 work_item_types_managed_at_workspace. The GET on the same path still works — reads are unaffected by mode, only writes are. Update the option through Property options (workspace), and see Work item type modes for how to detect which mode you are in.

Update a property option

curl -X PATCH \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/c1a7f2d8-6b34-4e59-9f80-2d4a7c31e6b5/options/9d3b5c71-2e48-4a6f-b1c9-7f0e83d25a64/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sev 1",
  "is_default": true
}'

import requests

response = requests.patch(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/c1a7f2d8-6b34-4e59-9f80-2d4a7c31e6b5/options/9d3b5c71-2e48-4a6f-b1c9-7f0e83d25a64/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "name": "Sev 1",
        "is_default": True,
    },
)
print(response.json())

const response = await fetch(
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/c1a7f2d8-6b34-4e59-9f80-2d4a7c31e6b5/options/9d3b5c71-2e48-4a6f-b1c9-7f0e83d25a64/",
  {
    method: "PATCH",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Sev 1",
      is_default: true,
    }),
  }
);
const data = await response.json();

Response200

{
  "id": "9d3b5c71-2e48-4a6f-b1c9-7f0e83d25a64",
  "name": "Sev 1",
  "description": "Customer-visible outage",
  "is_default": true,
  "sort_order": 15000,
  "external_id": null,
  "external_source": null
}

Response400

{
  "type": "https://api.plane.so/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "code": "validation_error",
  "detail": "The request body failed validation.",
  "errors": [
    {
      "field": "name",
      "message": "Ensure this field has no more than 255 characters."
    }
  ]
}