Update a workspace property option

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.

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.

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.

property_id:requiredstring (uuid)

The workspace-level property the option belongs to. See Workspace work item properties.

pk:requiredstring (uuid)

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.

name:optionalstring

The choice as it is displayed. Maximum 255 characters.

description:optionalstring

Free-form text explaining when to pick this choice.

is_default:optionalboolean

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 invalid_request, so clear the current default first and then set the new one.

external_id:optionalstring

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

external_source:optionalstring

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	invalid_request	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.
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 this workspace's properties.
404	not_found	No such workspace, workspace-level property, or option — 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. Use the project-level options endpoint.
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 property option

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

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

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

Response200

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

Response400

{
  "type": "invalid_request",
  "code": "invalid_request",
  "detail": "Only one option can be the default."
}

Moving the default

There is no automatic hand-off, so promoting a new default takes two requests:

1. PATCH the option that currently has is_default: true with {"is_default": false}.
2. PATCH the new option with {"is_default": true}.

Run it the other way round and the promotion is the request that fails, leaving the existing default untouched. Nothing is half-applied either way.