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. Use it to find which fields exist before writing values, and to 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 properties not yet attached to any work item type. To see what a specific type 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 show 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. Use the next value from the response instead of computing offsets yourself.

paginate:optionalstring

Set to cursor to switch to the keyset envelope, which skips the COUNT query and returns next_cursor and has_more instead of next and total_count. Leave it out to get 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. 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 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 returns 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