List property contexts
Return every context defined on a workspace-level property, as a paginated list. Use it to see where a property applies and how it behaves in each place before you add a new context or edit an existing one.
Read the whole list rather than a single context when you need to reason about precedence: a context's effect depends on which other contexts exist. Contexts are returned in sort_order by default.
Path parameters
slug:requiredstringThe 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 property whose contexts you want. A project-level property id is not addressable here and returns 404 not_found.
Query parameters
Check the spelling of order_by and paginate. Neither is validated, so a misspelled value fails silently. An unrecognized order_by value 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:optionalstringField to sort by. Prefix with - for descending.
sort_order,-sort_order: the property's own context order. This is the default.created_at,-created_at: when each context was addedid,-id
Pagination
per_page:optionalintegerPage size. Defaults to 50, maximum 200. A property usually has a handful of contexts, so one page is normally the whole set.
offset:optionalintegerNumber 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:optionalstringSet 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. Pair it with order_by=created_at or order_by=id. The default sort_order ordering isn't unique, so it can't be used with a cursor, and the request is rejected with ordering_not_cursor_eligible.
count:optionalbooleanDefaults to true. Set to false to skip the COUNT(*) behind total_count. The field is then omitted from the response.
Response shaping
fields:optionalstringComma-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: applies_to_all_projects, applies_to_all_work_item_types, created_at, default_value, external_id, external_source, id, is_default, is_multi, is_required, issue_type_ids, name, options, project_ids, settings, sort_order, updated_at, updated_by_id.
See Sparse fields.
Scopes
workspaces.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 workspace property settings. |
404 | not_found | No such workspace or property, 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 contexts does not depend on how the workspace manages work item types. Only POST, PATCH, and DELETE depend on the mode. See Work item type modes.
curl -X GET \
"https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/d1f7a3c9-5b62-4e08-9a41-7c3e2f8b6d05/contexts/?order_by=sort_order&per_page=50" \
-H "X-Api-Key: $PLANE_API_KEY"import requests
response = requests.get(
"https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/d1f7a3c9-5b62-4e08-9a41-7c3e2f8b6d05/contexts/",
headers={"X-Api-Key": "your-api-key"},
params={"order_by": "sort_order", "per_page": 50},
)
print(response.json())const params = new URLSearchParams({ order_by: "sort_order", per_page: "50" });
const response = await fetch(
`https://api.plane.so/api/v2/workspaces/my-team/work-item-properties/d1f7a3c9-5b62-4e08-9a41-7c3e2f8b6d05/contexts/?${params}`,
{
headers: {
"X-Api-Key": "your-api-key",
},
},
);
const data = await response.json();{
"data": [
{
"id": "2f8c40a6-9d13-4b7e-85c0-1e6a3f9b7d52",
"name": "Default",
"is_required": false,
"is_multi": false,
"is_default": true,
"default_value": [],
"settings": {},
"sort_order": 65535,
"applies_to_all_projects": true,
"applies_to_all_work_item_types": true,
"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,
"project_ids": [],
"issue_type_ids": [],
"options": [
{
"id": "5d0a9e34-7c62-4f18-b93d-0a4e6f2c8b71",
"name": "Low",
"is_default": false,
"sort_order": 10000
},
{
"id": "81b4f27c-3a05-4e96-8d21-7f6c0b4a9e53",
"name": "High",
"is_default": false,
"sort_order": 20000
}
]
},
{
"id": "6e2b90d4-1c73-4f58-a09e-3d8b5c14e7f2",
"name": "Bug severity",
"is_required": true,
"is_multi": false,
"is_default": false,
"default_value": [],
"settings": {},
"sort_order": 75535,
"applies_to_all_projects": false,
"applies_to_all_work_item_types": false,
"external_id": null,
"external_source": null,
"created_at": "2026-02-03T11:05:17.204918Z",
"updated_at": "2026-02-03T11:05:17.204918Z",
"updated_by_id": null,
"project_ids": [
"4af68566-94a4-4eb3-94aa-50dc9427067b",
"9c3d7e21-6b45-4a80-8f19-2e0c7b5d3a64"
],
"issue_type_ids": ["b7e04a95-2f18-4c63-9d57-8a12e6b0f439"],
"options": [
{
"id": "c58e2f01-4d97-4b3a-8e26-1f0b7a9c5d34",
"name": "S1 — Critical",
"is_default": false,
"sort_order": 10000
},
{
"id": "a49b6c72-8e15-4d30-b57c-2f81e0a6d938",
"name": "S2 — Major",
"is_default": true,
"sort_order": 20000
},
{
"id": "f13c8a60-7d24-4e59-9b02-6a5f1c3e8d47",
"name": "S3 — Minor",
"is_default": false,
"sort_order": 30000
}
]
}
],
"next": null,
"previous": null,
"total_count": 2,
"pagination": {
"style": "offset"
}
}{
"data": [
{
"id": "2f8c40a6-9d13-4b7e-85c0-1e6a3f9b7d52",
"name": "Default",
"is_required": false,
"is_multi": false,
"is_default": true,
"default_value": [],
"settings": {},
"sort_order": 65535,
"applies_to_all_projects": true,
"applies_to_all_work_item_types": true,
"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,
"project_ids": [],
"issue_type_ids": [],
"options": []
}
],
"next_cursor": "b3A9MTcx",
"has_more": true,
"pagination": {
"style": "cursor"
}
}Reading the scope of each row
Two fields decide coverage on each axis, and you need to read them in the right order:
applies_to_all_projectsfirst,project_idssecond. The first row above covers every project. Itsproject_idsis empty because of the wildcard, not because the scope is empty.applies_to_all_work_item_typesfirst,issue_type_idssecond, read the same way.
Rank the rows to find which one a given work item uses. The most specific wins: listed projects and listed types beat listed projects and all types, which beat all projects and listed types, which beat all projects and all types. See Property contexts overview for the full precedence rules.