Get a work item property

GET/api/v2/workspaces/{slug}/projects/{project_id}/work-item-properties/{pk}/

Retrieve one property definition by id. Use it when you already have a property id (from a type's property list, a stored mapping, or a create response) and need its current shape before reading or writing values.

The response includes the resolved options array, so a single request tells you both what the field is and which choices it offers. Check property_type before you build a value: it decides what the field can hold, and relation_type narrows it further for RELATION properties.

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 the property belongs to. A property id from a different project returns 404, even inside the same workspace.

pk:requiredstring (uuid)

The id of the property to retrieve.

Response shaping

fields:optionalstring

Comma-separated list of fields to return. Fields you don't request are left out of the response instead of coming back as null, so a missing key means you didn't ask for it and null means the value is null. id is always included, whether or not you name it.

Pass all to get every requestable field. An unknown field name returns 400 with the list of valid names and the closest match, so a typo is caught instead of being silently ignored.

Requestable here: created_at, default_value, description, display_name, external_id, external_source, id, is_active, is_multi, is_required, logo_props, name, options, property_type, relation_type, settings, updated_at, updated_by_id, validation_rules.

See Sparse fields.

Scopes

projects.work_item_properties:read

Errors

Status	Code	Cause
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 read this project's properties.
404	not_found	No such property, project, or workspace, or it's outside your tenant.
406	not_acceptable	The Accept header asks for a representation the API can't produce.
429	rate_limited	Throttled. Honor the Retry-After header before retrying.

Reads ignore the mode

This endpoint works whether the workspace manages work item types at the project or workspace level. Only writes are mode-specific, and only writes return a 409. See Work item type modes.

No expansion on properties

Work item properties don't accept ?expand=. The response is the object shown here, with options already resolved inline.

Records outside your tenant return 404

A property outside your tenant returns 404, not 403. If a cached id starts returning 404, re-read the catalog with List work item properties rather than retrying.

Get a work item property

curl -X GET \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/9d2f0b74-6a51-4c8e-b3d7-2f1a8c05e964/" \
  -H "X-Api-Key: $PLANE_API_KEY"

import requests

response = requests.get(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/9d2f0b74-6a51-4c8e-b3d7-2f1a8c05e964/",
    headers={"X-Api-Key": "your-api-key"},
)
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/9d2f0b74-6a51-4c8e-b3d7-2f1a8c05e964/",
  {
    headers: {
      "X-Api-Key": "your-api-key",
    },
  },
);
const data = await response.json();

Response200

{
  "id": "9d2f0b74-6a51-4c8e-b3d7-2f1a8c05e964",
  "name": "severity",
  "display_name": "Severity",
  "description": "How badly this affects customers",
  "property_type": "OPTION",
  "relation_type": null,
  "is_multi": false,
  "is_required": true,
  "is_active": true,
  "default_value": [],
  "options": [
    {
      "id": "3e7a5c19-42b8-4d06-9f3e-7c1b8a0d2456",
      "name": "Critical",
      "description": "Production is down",
      "parent_id": null,
      "is_default": false,
      "is_active": true,
      "sort_order": 15000,
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "updated_at": "2026-01-14T09:22:41.478363Z",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    },
    {
      "id": "b6c04f83-1d29-4e57-8a3b-90e2f5c7d418",
      "name": "Major",
      "description": "A core workflow is broken",
      "parent_id": null,
      "is_default": true,
      "is_active": true,
      "sort_order": 25000,
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "updated_at": "2026-01-14T09:22:41.478363Z",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    },
    {
      "id": "7f52d3a8-0e14-4c69-b28d-a1f6e903c5b7",
      "name": "Minor",
      "description": "Cosmetic or low impact",
      "parent_id": null,
      "is_default": false,
      "is_active": true,
      "sort_order": 35000,
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "updated_at": "2026-01-14T09:22:41.478363Z",
      "updated_by_id": "16c61a3a-512a-48ac-b0be-b6b46fe6f430"
    }
  ],
  "settings": {},
  "validation_rules": {},
  "logo_props": {},
  "external_id": null,
  "external_source": null,
  "created_at": "2026-01-14T09:22:41.478363Z",
  "updated_at": "2026-01-14T09:22:41.478363Z",
  "updated_by_id": null
}

Response404

{
  "type": "not_found",
  "code": "not_found",
  "detail": "No IssueProperty matches the given query."
}

name is the stable key, display_name is the label

Fields get renamed. If you store a mapping between a Plane property and a field in your own system, key it on id. Use name when you need something human-readable that changes less often than the label. display_name is the label shown in the UI, and the field you send to change it.