List work item properties

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

Return every custom property defined in a project as a paginated list. This is how you discover which fields exist before writing values, and how you resolve a field's label to the property id you need for options and type attachments.

The list is the project's full catalog of definitions — including properties with is_active: false, and including properties not yet attached to any work item type. To see what a specific type actually offers, use List type properties instead.

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 whose properties you want to list.

Query Parameters

Filters combine with AND. There is no search.

name:optionalstring

Return properties whose name slug matches, compared case-insensitively. ?name=story-points matches the property whose display_name is Story Points.

display_name:optionalstring

Return properties whose display_name matches, compared case-insensitively. ?display_name=severity matches Severity.

external_id:optionalstring

Return properties whose external_id matches exactly. Use it to find the property you created earlier for a field in another system.

external_source:optionalstring

Return properties from one source system, for example jira. Combine it with external_id, because an external_id is unique only within its source.

Check your spelling on order_by and paginate. Neither is validated: an unrecognized order_by falls back to the default ordering, and anything other than paginate=cursor uses offset pagination. A typo shows up as an unexpected sort order or envelope, not as an error.

Ordering

order_by:optionalstring

Field to sort by. Prefix with - for descending.

sort_order , -sort_order — the configured display order of the fields
created_at , -created_at — when each property was defined
id , -id

Order by sort_order when you are rendering the fields to a person; it is the order the project itself uses.

Pagination

per_page:optionalinteger

Page size. Defaults to 50, maximum 200. Most projects define far fewer than 50 properties, so one page is usually the whole catalog.

offset:optionalinteger

Number of rows to skip from the start of the result set. Maximum 10000. Read the next value from the response rather than computing offsets yourself.

paginate:optionalstring

Set to cursor to opt into the COUNT-free keyset envelope, which returns next_cursor and has_more instead of next and total_count. Omit it for the default offset envelope.

count:optionalboolean

Defaults to true. Set to false to skip the COUNT(*) behind total_count; the field is then omitted from the response.

Response shaping

fields:optionalstring

Comma-separated list of fields to return on each row. Unrequested keys are omitted from the response, not returned as null, so absent means "not requested" and null means "actually null". id always comes back whether or not you name it.

Pass all for every requestable field. An unknown name is a 400 that lists the valid set and suggests the closest match, so a typo can't silently cost you the saving.

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 workspace or project, 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 work in either mode

Listing properties never returns a mode conflict. A project still surfaces its properties when the workspace manages work item types at the workspace level — only writes are mode-specific. See Work item type modes.

List work item properties

bash

curl -X GET \
  "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/?order_by=sort_order&per_page=50" \
  -H "X-Api-Key: $PLANE_API_KEY"

python

import requests

response = requests.get(
    "https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/",
    headers={"X-Api-Key": "your-api-key"},
    params={"order_by": "sort_order", "per_page": 50},
)
print(response.json())

javascript

const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
const response = await fetch(
  `https://api.plane.so/api/v2/workspaces/my-team/projects/4af68566-94a4-4eb3-94aa-50dc9427067b/work-item-properties/?${params}`,
  {
    headers: {
      "X-Api-Key": "your-api-key",
    },
  },
);
const data = await response.json();

Response200

json

{
  "data": [
    {
      "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"
        }
      ],
      "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
    },
    {
      "id": "c81b7e2a-5f34-4d90-8e17-3a6c9b0f2d75",
      "name": "story_points",
      "display_name": "Story points",
      "description": "Relative sizing for planning",
      "property_type": "DECIMAL",
      "relation_type": null,
      "is_multi": false,
      "is_required": false,
      "is_active": true,
      "default_value": ["3"],
      "options": [],
      "settings": {},
      "validation_rules": {},
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "created_at": "2026-01-14T09:24:03.117482Z",
      "updated_at": "2026-01-14T09:24:03.117482Z",
      "updated_by_id": null
    },
    {
      "id": "5a3e8f01-7c62-4b18-a940-d2e5b7c86139",
      "name": "reviewer",
      "display_name": "Reviewer",
      "description": "Who signs this off",
      "property_type": "RELATION",
      "relation_type": "USER",
      "is_multi": true,
      "is_required": false,
      "is_active": true,
      "default_value": [],
      "options": [],
      "settings": {},
      "validation_rules": {},
      "logo_props": {},
      "external_id": null,
      "external_source": null,
      "created_at": "2026-01-14T09:26:55.902314Z",
      "updated_at": "2026-01-14T09:26:55.902314Z",
      "updated_by_id": null
    }
  ],
  "next": null,
  "previous": null,
  "total_count": 3,
  "pagination": {
    "style": "offset"
  }
}

Response200

json

{
  "data": [
    {
      "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": [],
      "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
    }
  ],
  "next_cursor": "b3A9MTcx",
  "has_more": true,
  "pagination": {
    "style": "cursor"
  }
}

Inactive properties still appear

is_active: false means the field is no longer offered on new edits, not that it is gone. The list returns it. If you are rendering a form, filter to is_active: true yourself — and check the type's own property list, since a property in this catalog may not be attached to the type you are editing.

List work item properties ​

Path Parameters ​

Query Parameters ​

Ordering ​

Pagination ​

Response shaping ​

Scopes ​

Errors ​

List work item properties

Path Parameters

Query Parameters

Ordering

Pagination

Response shaping

Scopes

Errors