feat: rich filters + pql on work-item list endpoints, add list_workspace

dheeru0198 · claude · dheeru0198 · commit d55f45ea8e0e · 2026-05-26T14:22:44.000+05:30
Expose the new external API's structured filtering capability on every work-item list method in the SDK. - WorkItemQueryParams now accepts `filters: dict[str, Any] | None` (the existing `pql: str | None` field is unchanged). A small `_prepare_work_item_params` helper JSON-encodes `filters` into the `filters=` query string the API expects. - New `WorkItems.list_workspace(workspace_slug, params)` calling `GET /workspaces/<slug>/work-items/` — paginated, total_results, spans every project the caller can view. - `WorkItems.list` and `WorkItems.list_archived` now route through `_prepare_work_item_params`, so `filters` and `pql` work uniformly. - `Cycles.list_work_items` and `Modules.list_work_items` accept `WorkItemQueryParams` (typed path) with the same serialization, and still accept a plain `Mapping[str, Any]` for backwards compatibility. - Real-API unit tests for `filters` on `list`, plus `list_workspace` with and without `filters`. - Bump version to 0.2.13. Backend: makeplane/plane-ee#7376 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/README.md b/README.md
@@ -748,9 +748,55 @@ The SDK provides comprehensive Pydantic v2 models for all API operations.
 
 - `BaseQueryParams` - Base query parameters
 - `PaginatedQueryParams` - Pagination support (per_page, page)
-- `WorkItemQueryParams` - Work item specific queries (expand, order_by, etc.)
+- `WorkItemQueryParams` - Work item specific queries (expand, order_by, `filters`, `pql`, etc.)
 - `RetrieveQueryParams` - Retrieve operations (expand, fields, etc.)
 
+#### Filtering work items
+
+`WorkItemQueryParams` accepts two filter inputs that map to the same backend filter engine:
+
+- **`filters`** — a structured filter expression (dict). Supports nested
+  `and` / `or` / `not` groups and field operators (`__in`, `__gte`,
+  `__range`, `__icontains`, etc.). The SDK JSON-encodes this into the
+  `filters=` query parameter.
+- **`pql`** — a Plane Query Language string. Human-readable alternative
+  with the same expressive power.
+
+```python
+from plane.models.query_params import WorkItemQueryParams
+
+# Project-scoped, structured filters
+client.work_items.list(
+    "my-workspace",
+    "project-id",
+    params=WorkItemQueryParams(
+        filters={"and": [
+            {"priority": "urgent"},
+            {"state_group__in": ["unstarted", "started"]},
+        ]},
+        order_by="-created_at",
+        per_page=50,
+    ),
+)
+
+# Project-scoped, PQL
+client.work_items.list(
+    "my-workspace",
+    "project-id",
+    params=WorkItemQueryParams(pql='priority = "urgent" AND assignee = currentUser()'),
+)
+
+# Workspace-scoped — spans every project the caller can view, with
+# per-project authorization honored server-side
+client.work_items.list_workspace(
+    "my-workspace",
+    params=WorkItemQueryParams(filters={"priority": "urgent"}),
+)
+```
+
+The same `filters` and `pql` query parameters also work on `list_archived`,
+`cycles.list_work_items`, and `modules.list_work_items`.
+
 ### Response Models
 
 Paginated responses follow the pattern `Paginated<Resource>Response` and include:
diff --git a/plane/api/cycles.py b/plane/api/cycles.py
@@ -10,7 +10,9 @@
     TransferCycleWorkItemsRequest,
     UpdateCycle,
 )
+from ..models.query_params import WorkItemQueryParams
 from .base_resource import BaseResource
+from .work_items.base import _prepare_work_item_params
 
 
 class Cycles(BaseResource):
@@ -137,18 +139,28 @@ def list_work_items(
         workspace_slug: str,
         project_id: str,
         cycle_id: str,
-        params: Mapping[str, Any] | None = None,
+        params: WorkItemQueryParams | Mapping[str, Any] | None = None,
     ) -> PaginatedCycleWorkItemResponse:
         """List work items in a cycle.
 
+        Supports the same ``filters`` and ``pql`` query parameters as
+        :meth:`WorkItems.list`.
+
         Args:
             workspace_slug: The workspace slug identifier
             project_id: UUID of the project
             cycle_id: UUID of the cycle
-            params: Optional query parameters
+            params: Optional query parameters. Prefer ``WorkItemQueryParams``;
+                a plain mapping is also accepted for backwards compatibility
+                and is passed through unchanged.
         """
+        if isinstance(params, WorkItemQueryParams):
+            query_params: Mapping[str, Any] | None = _prepare_work_item_params(params)
+        else:
+            query_params = params
         response = self._get(
-            f"{workspace_slug}/projects/{project_id}/cycles/{cycle_id}/cycle-issues", params=params
+            f"{workspace_slug}/projects/{project_id}/cycles/{cycle_id}/cycle-issues",
+            params=query_params,
         )
         return PaginatedCycleWorkItemResponse.model_validate(response)
 
@@ -180,9 +192,7 @@ def archive(self, workspace_slug: str, project_id: str, cycle_id: str) -> bool:
             project_id: UUID of the project
             cycle_id: UUID of the cycle
         """
-        self._post(
-            f"{workspace_slug}/projects/{project_id}/cycles/{cycle_id}/archive", {}
-        )
+        self._post(f"{workspace_slug}/projects/{project_id}/cycles/{cycle_id}/archive", {})
         return True
 
     def unarchive(self, workspace_slug: str, project_id: str, cycle_id: str) -> bool:
@@ -193,7 +203,5 @@ def unarchive(self, workspace_slug: str, project_id: str, cycle_id: str) -> bool
             project_id: UUID of the project
             cycle_id: UUID of the cycle
         """
-        self._delete(
-            f"{workspace_slug}/projects/{project_id}/archived-cycles/{cycle_id}/unarchive"
-        )
+        self._delete(f"{workspace_slug}/projects/{project_id}/archived-cycles/{cycle_id}/unarchive")
         return True
diff --git a/plane/api/modules.py b/plane/api/modules.py
@@ -9,7 +9,9 @@
     PaginatedModuleWorkItemResponse,
     UpdateModule,
 )
+from ..models.query_params import WorkItemQueryParams
 from .base_resource import BaseResource
+from .work_items.base import _prepare_work_item_params
 
 
 class Modules(BaseResource):
@@ -136,19 +138,28 @@ def list_work_items(
         workspace_slug: str,
         project_id: str,
         module_id: str,
-        params: Mapping[str, Any] | None = None,
+        params: WorkItemQueryParams | Mapping[str, Any] | None = None,
     ) -> PaginatedModuleWorkItemResponse:
         """List work items in a module.
 
+        Supports the same ``filters`` and ``pql`` query parameters as
+        :meth:`WorkItems.list`.
+
         Args:
             workspace_slug: The workspace slug identifier
             project_id: UUID of the project
             module_id: UUID of the module
-            params: Optional query parameters
+            params: Optional query parameters. Prefer ``WorkItemQueryParams``;
+                a plain mapping is also accepted for backwards compatibility
+                and is passed through unchanged.
         """
+        if isinstance(params, WorkItemQueryParams):
+            query_params: Mapping[str, Any] | None = _prepare_work_item_params(params)
+        else:
+            query_params = params
         response = self._get(
             f"{workspace_slug}/projects/{project_id}/modules/{module_id}/module-issues",
-            params=params,
+            params=query_params,
         )
         return PaginatedModuleWorkItemResponse.model_validate(response)
 
diff --git a/plane/api/work_items/base.py b/plane/api/work_items/base.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 from typing import Any
 
 from ...models.query_params import RetrieveQueryParams, WorkItemQueryParams
@@ -23,6 +24,21 @@
 from .work_logs import WorkLogs
 
 
+def _prepare_work_item_params(params: WorkItemQueryParams | None) -> dict[str, Any] | None:
+    """Serialize WorkItemQueryParams for use as HTTP query params.
+
+    The ``filters`` field is a structured object but the API expects it as a
+    JSON string in a single ``filters=`` query parameter. Everything else is
+    passed through as-is by ``requests``' query-string encoder.
+    """
+    if params is None:
+        return None
+    payload = params.model_dump(exclude_none=True)
+    if "filters" in payload and isinstance(payload["filters"], dict):
+        payload["filters"] = json.dumps(payload["filters"], separators=(",", ":"))
+    return payload
+
+
 class WorkItems(BaseResource):
     def __init__(self, config: Any) -> None:
         super().__init__(config, "/workspaces/")
@@ -157,23 +173,67 @@ def list(
             project_id: UUID of the project
             params: Optional query parameters for filtering, ordering, and pagination
 
-        Example:
-            from plane.models.schemas import WorkItemQueryParams
+        Example::
 
-            # List work items with filters
+            from plane.models.query_params import WorkItemQueryParams
+
+            # PQL filter (human-readable)
+            work_items = client.work_items.list(
+                "my-workspace",
+                "project-id",
+                params=WorkItemQueryParams(pql='priority = "urgent"'),
+            )
+
+            # Structured `filters` (JSON-encoded into the query string)
             work_items = client.work_items.list(
                 "my-workspace",
                 "project-id",
                 params=WorkItemQueryParams(
-                    priority="high",
-                    state="state-id",
-                    expand="assignees,labels"
-                )
+                    filters={"and": [
+                        {"priority": "urgent"},
+                        {"state_group__in": ["unstarted", "started"]},
+                    ]},
+                ),
+            )
+        """
+        response = self._get(
+            f"{workspace_slug}/projects/{project_id}/work-items",
+            params=_prepare_work_item_params(params),
+        )
+        return PaginatedWorkItemResponse.model_validate(response)
+
+    def list_workspace(
+        self,
+        workspace_slug: str,
+        params: WorkItemQueryParams | None = None,
+    ) -> PaginatedWorkItemResponse:
+        """List work items across an entire workspace.
+
+        Returns a paginated envelope of work items the caller can view,
+        spanning every project in the workspace (per-project authorization
+        and conditional grants are honored server-side).
+
+        Args:
+            workspace_slug: The workspace slug identifier
+            params: Optional query parameters — supports ``filters``, ``pql``,
+                ``order_by``, ``cursor``, ``per_page``, ``fields``, ``expand``.
+
+        Example::
+
+            from plane.models.query_params import WorkItemQueryParams
+
+            results = client.work_items.list_workspace(
+                "my-workspace",
+                params=WorkItemQueryParams(
+                    filters={"priority": "urgent"},
+                    order_by="-created_at",
+                    per_page=50,
+                ),
             )
         """
-        query_params = params.model_dump(exclude_none=True) if params else None
         response = self._get(
-            f"{workspace_slug}/projects/{project_id}/work-items", params=query_params
+            f"{workspace_slug}/work-items",
+            params=_prepare_work_item_params(params),
         )
         return PaginatedWorkItemResponse.model_validate(response)
 
@@ -247,14 +307,17 @@ def list_archived(
     ) -> PaginatedWorkItemResponse:
         """List archived work items in a project.
 
+        Supports the same ``filters`` and ``pql`` query parameters as
+        :meth:`list`.
+
         Args:
             workspace_slug: The workspace slug identifier
             project_id: UUID of the project
             params: Optional query parameters for filtering, ordering, and pagination
         """
-        query_params = params.model_dump(exclude_none=True) if params else None
         response = self._get(
-            f"{workspace_slug}/projects/{project_id}/archived-work-items", params=query_params
+            f"{workspace_slug}/projects/{project_id}/archived-work-items",
+            params=_prepare_work_item_params(params),
         )
         return PaginatedWorkItemResponse.model_validate(response)
 
@@ -286,6 +349,4 @@ def unarchive(self, workspace_slug: str, project_id: str, work_item_id: str) ->
         Returns:
             None (HTTP 204 No Content)
         """
-        self._delete(
-            f"{workspace_slug}/projects/{project_id}/work-items/{work_item_id}/unarchive"
-        )
+        self._delete(f"{workspace_slug}/projects/{project_id}/work-items/{work_item_id}/unarchive")
diff --git a/plane/models/query_params.py b/plane/models/query_params.py
@@ -1,5 +1,7 @@
 """Query parameter DTOs for list/retrieve endpoints."""
 
+from typing import Any
+
 from pydantic import BaseModel, ConfigDict, Field
 
 
@@ -58,12 +60,28 @@ class WorkItemQueryParams(PaginatedQueryParams):
     - fields: Comma-separated fields to include
     - order_by: Field to order by (prefix with '-' for descending)
     - per_page: Number of results per page (1-100)
-    - pql: PQL filters
+    - pql: Plane Query Language expression for structured filtering
+    - filters: JSON-serializable filter expression for structured filtering
     """
 
     model_config = ConfigDict(extra="ignore", populate_by_name=True)
 
-    pql: str | None = Field(None, description="PQL filters")
+    pql: str | None = Field(
+        None,
+        description=(
+            "Plane Query Language expression. Human-readable alternative to "
+            '`filters`. Example: `priority = "urgent" AND assignee = currentUser()`.'
+        ),
+    )
+    filters: dict[str, Any] | None = Field(
+        None,
+        description=(
+            "Structured filter expression. Supports nested `and`/`or`/`not` groups "
+            "and field comparisons with operators like `__in`, `__gte`, `__range`, "
+            "`__isnull`, `__icontains`, etc. JSON-encoded into the `filters=` "
+            "query param by the client."
+        ),
+    )
 
 
 class RetrieveQueryParams(BaseQueryParams):
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plane-sdk"
-version = "0.2.12"
+version = "0.2.13"
 description = "Python SDK for Plane API"
 readme = "README.md"
 requires-python = ">=3.10"
diff --git a/tests/unit/test_work_items.py b/tests/unit/test_work_items.py
