Create a property option

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

Add one more selectable choice to a project-level property whose property_type is OPTION. The new option becomes immediately pickable on work items that carry the property.

Use this when the property already exists and you are extending its list. If you are still creating the property, you can pass the full set of choices inline through the property's write-only options field instead — see Work item properties — and come back here 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. Worth filling in when the label alone doesn't tell someone when to choose it.

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 alongside external_id — an external_id is only unique within its source.

sort_order is not writable

sort_order comes back on every read, but it is not a create field. Plane assigns the new option a position when it is created; there is no body parameter that places it.

Scopes

projects.work_item_properties:write

Errors

Status	Code	Cause
400	validation_error	name missing, or a field over its 255-character limit.
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 property, project, or workspace — or the property belongs to a different project.
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

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 option isn't missing and you aren't unauthorized, the write simply belongs on the workspace surface. Create it through Property options (workspace) instead, and see Work item type modes for how 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",
  "is_default": false,
  "sort_order": 45000,
  "external_id": null,
  "external_source": null
}

Response409

{
  "type": "https://api.plane.so/errors/work-item-types-managed-at-workspace",
  "title": "Conflict",
  "status": 409,
  "code": "work_item_types_managed_at_workspace",
  "detail": "Work item types are managed at the workspace level for this workspace."
}