Create a property option

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

Add a selectable choice to a project-level property whose property_type is OPTION. Work items that have the property can use the new option right away.

Use this endpoint to add choices to a property that already exists. When you create the property, you can instead pass the full set of choices inline through its write-only options field (see Work item properties) and use this endpoint only for later changes.

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 property to add the option to. It must be an OPTION property in this project. A property id from another project returns 404.

Body parameters

name:requiredstring

The label shown in the picker, for example Blocker. Maximum 255 characters.

description:optionalstring

Free-form explanation of what the option means. Fill it in when the label alone doesn't tell people when to choose the option.

is_default:optionalboolean

Make this the option that is preselected when a work item is created without an explicit value for this property. Defaults to false.

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. Send it with external_id, because an external_id is unique only within its source.

sort_order is not writable

sort_order is returned on every read, but you can't set it on create. Plane assigns the new option a position, and no body parameter controls it.

Scopes

projects.work_item_properties:write

Errors

Status	Code	Cause
400	invalid_request	name missing, or a field over its 255-character 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 this project's properties.
404	not_found	No such property, project, or workspace, or the property belongs to a different project.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
409	conflict	The workspace manages work item types at the workspace level, so this project-level write is rejected.
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.

Wrong mode returns 409, not 404

A workspace manages work item types in exactly one mode. If yours is in workspace mode, this project-level POST returns 409 work_item_types_managed_at_workspace. The error doesn't mean anything is missing or that you lack permission. In that mode, the write belongs on the workspace-level endpoints. Create the option through Property options (workspace) instead, and see Work item type modes to detect the mode first.

Create a property option

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/c1a7f2d8-6b34-4e59-9f80-2d4a7c31e6b5/options/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Blocker",
  "description": "Stops all downstream work",
  "is_default": false
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/c1a7f2d8-6b34-4e59-9f80-2d4a7c31e6b5/options/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "name": "Blocker",
        "description": "Stops all downstream work",
        "is_default": False,
    },
)
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/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Blocker",
      description: "Stops all downstream work",
      is_default: false,
    }),
  },
);
const data = await response.json();

Response201

{
  "id": "6f0c8a24-51d7-4e93-bb62-0a7e5c1d9483",
  "name": "Blocker",
  "description": "Stops all downstream work",
  "parent_id": null,
  "is_default": false,
  "is_active": true,
  "sort_order": 45000,
  "logo_props": {},
  "external_id": null,
  "external_source": null,
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "updated_by_id": null
}

Response409

{
  "type": "conflict",
  "code": "work_item_types_managed_at_workspace",
  "detail": "Work item types are managed at the workspace level for this workspace."
}