Create a workspace property option

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

Add a choice to a workspace-level OPTION property. The new option is appended to the end of the property's list and becomes immediately selectable on work items across the workspace.

The property must have property_type: "OPTION". Posting an option to a property of any other type returns 400 validation_error — the option list is meaningless for a TEXT or DECIMAL property.

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 — add 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 OPTION property to add the choice to. A project-scoped property id is a 404 here — this path never crosses into a project. See Workspace work item properties.

Body Parameters

name:requiredstring

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. At most one option per property can be the default, and there is no automatic hand-off: if another option already has it, this request is rejected with 400 validation_error. Clear the current default with a PATCH first.

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. Plane appends the new option after the current last one, so create options in the order you want them displayed.

Scopes

workspaces.work_item_properties:write

Errors

Status	Code	Cause
400	validation_error	Missing name, a field over 255 characters, is_default when the property already has a default, or a property whose property_type is not OPTION.
401	unauthorized	Missing or invalid credentials.
403	forbidden	Your role or token scope can't write this workspace's properties.
404	resource_not_found	No such workspace or workspace-level property, or it's outside your tenant.
409	work_item_types_managed_at_project	This workspace manages work item types at the project level. Use the project-level options endpoint.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Create a property option

curl -X POST \
  "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/" \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sandbox",
  "description": "Reported on an isolated test tenant",
  "external_id": "env-sandbox",
  "external_source": "servicedesk"
}'

import requests

response = requests.post(
    "https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/9d0e1f3b-6a72-4c85-9e4d-2b7f1a6c8d54/options/",
    headers={"X-Api-Key": "your-api-key"},
    json={
        "name": "Sandbox",
        "description": "Reported on an isolated test tenant",
        "external_id": "env-sandbox",
        "external_source": "servicedesk",
    },
)
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/",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Sandbox",
      description: "Reported on an isolated test tenant",
      external_id: "env-sandbox",
      external_source: "servicedesk",
    }),
  }
);
const data = await response.json();

Response201

{
  "id": "2f6a94c1-7b38-4d50-91ae-3c0d5e8b7a26",
  "name": "Sandbox",
  "description": "Reported on an isolated test tenant",
  "is_default": false,
  "sort_order": 40000,
  "external_id": "env-sandbox",
  "external_source": "servicedesk"
}

Response409

{
  "type": "https://api.plane.so/errors/work_item_types_managed_at_project",
  "title": "Work Item Types Managed At Project",
  "status": 409,
  "code": "work_item_types_managed_at_project",
  "detail": "Work item types are managed at the project level for this workspace."
}

Seeding a whole option set

Create the options in display order in one pass, then set the default with a follow-up PATCH. That keeps every create request free of is_default and avoids tripping the one-default rule when a request is retried.