List projects in a workspace (lite, paginated).

Trimmed fields: id, identifier, name, description, emoji, icon_prop, cover_image, cover_image_url, archived_at. For full detail use retrieve_project.

Args: cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (1-1000, default 1000). order_by: Sort field; prefix '-' for descending.

Returns: Paginated envelope: results + total_count, next_cursor, next_page_results (page again while next_page_results is true).

Create a new project.

Args: workspace_slug: The workspace slug identifier name: Project name identifier: Project identifier (e.g., "MP" for "My Project") description: Project description project_lead: UUID of the project lead user default_assignee: UUID of the default assignee user emoji: Emoji for the project cover_image: Cover image URL or asset ID module_view: Enable module view cycle_view: Enable cycle view issue_views_view: Enable issue views view page_view: Enable page view intake_view: Enable intake view guest_view_all_features: Allow guests to view all features archive_in: Days until auto-archive close_in: Days until auto-close timezone: Project timezone external_source: External system source name external_id: External system identifier is_issue_type_enabled: Enable issue types

Returns: Created Project object

Retrieve a project by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project

Returns: Project object

Update a project by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project name: Project name description: Project description project_lead: UUID of the project lead user default_assignee: UUID of the default assignee user identifier: Project identifier emoji: Emoji for the project cover_image: Cover image URL or asset ID network: Project visibility (0=secret, 2=public) module_view: Enable module view cycle_view: Enable cycle view issue_views_view: Enable issue views view page_view: Enable page view intake_view: Enable intake view guest_view_all_features: Allow guests to view all features archive_in: Days until auto-archive close_in: Days until auto-close timezone: Project timezone external_source: External system source name external_id: External system identifier is_issue_type_enabled: Enable issue types is_time_tracking_enabled: Enable time tracking default_state: UUID of the default state estimate: Estimate configuration

Returns: Updated Project object

Delete a project by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project

Archive or unarchive a project.

Archived projects are hidden from active project lists but not deleted. All work items, cycles, and modules are preserved.

Args: project_id: UUID of the project archive: True to archive the project, False to unarchive it

Get work log summary for a project.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project

Returns: List of ProjectWorklogSummary objects containing work item IDs and durations

List members of a project (filterable, paginated).

Optional filters first_name/last_name/email/display_name (case-insensitive contains), role_slug (exact), is_active, is_bot - combined with AND.

Args: project_id: UUID of the project. cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (1-1000, default 100). order_by: Sort field; prefix '-' for descending.

Returns: Paginated envelope: results (members incl. role, role_slug, is_active, is_bot) + total_count, next_cursor, next_page_results.

Update features of a project.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project modules: Enable/disable modules feature cycles: Enable/disable cycles feature views: Enable/disable views feature pages: Enable/disable pages feature intakes: Enable/disable intakes feature work_item_types: Enable/disable work item types feature

Returns: Updated ProjectFeature object

Get the estimate configuration for a project.

Returns the active estimate system including its ID, which is required to call list_project_estimate_points.

Args: project_id: UUID of the project

Returns: Estimate object with id, name, and type fields

List all valid estimate points for a project.

Use this to discover the available estimate point UUIDs before calling update_work_item with an estimate_point value. Each EstimatePoint has an id (UUID to pass to update_work_item) and a value (display label such as "1", "2", "3", "5", "8" or "XS", "S", "M", "L", "XL").

Workflow: 1. Call get_project_estimate to get the estimate_id 2. Call list_project_estimate_points with that estimate_id 3. Pick the EstimatePoint whose value matches the user's intent 4. Pass that EstimatePoint.id to update_work_item(estimate_point=...)

Args: project_id: UUID of the project estimate_id: UUID of the estimate (from get_project_estimate)

Returns: List of EstimatePoint objects, each with id and value fields

Create a new estimate for a project.

Args: project_id: UUID of the project name: Name of the estimate (e.g., "Story Points", "T-Shirt Sizes") type: Estimate type - "categories", "points", or "time" description: Optional description last_used: Whether this becomes the active estimate (default True) external_id: External system identifier external_source: External system source name

Returns: Created Estimate object

Update the estimate for a project.

Args: project_id: UUID of the project name: New name for the estimate description: New description external_id: External system identifier external_source: External system source name

Returns: Updated Estimate object

Delete the estimate for a project.

Args: project_id: UUID of the project

Link an estimate to a project, making it the active estimate system.

Args: project_id: UUID of the project estimate_id: UUID of the estimate to activate

Returns: Updated Project object

Create estimate points for a project estimate.

Each point dict may have: value (required, max 20 chars), key (int), description, external_id, external_source.

Example: points=[ {"value": "1", "key": 0}, {"value": "2", "key": 1}, {"value": "3", "key": 2}, {"value": "5", "key": 3}, {"value": "8", "key": 4}, ]

Args: project_id: UUID of the project estimate_id: UUID of the estimate points: List of point definitions

Returns: List of created EstimatePoint objects

Update a single estimate point.

Args: project_id: UUID of the project estimate_id: UUID of the estimate estimate_point_id: UUID of the estimate point to update value: New display value (max 20 chars, e.g. "XL", "13") key: New sort key (integer) description: New description external_id: External system identifier external_source: External system source name

Returns: Updated EstimatePoint object

Delete a single estimate point.

Args: project_id: UUID of the project estimate_id: UUID of the estimate estimate_point_id: UUID of the estimate point to delete

List work items with optional PQL filtering.

Omit project_id to list across the entire workspace. Pass project_id to scope results to a single project.

For UUID fields (assignee, state, label, cycle, module, type, milestone) call the relevant list tool first to get the UUID.

Args: project_id: UUID of the project. Omit for workspace-wide results. pql: PQL filter. See field description for syntax. order_by: Sort field; prefix - for descending (e.g. -created_at). per_page: 1-100, default 25. cursor: From previous response's next_cursor. expand: Comma-separated relations to expand (e.g. assignees,labels,state). fields: Sparse fieldset - id, name, sequence_id, priority, state, project, assignees, labels, type_id, description_html, start_date, target_date, created_at, updated_at, created_by, is_draft. Use project (not project_id) and description_html (there is no description field). Any field you omit or misname comes back null - a null here does NOT mean the item lacks that value; it means it was not requested. To read the description, include description_html; for the type, include type_id. external_id / external_source: Filter by external system.

Returns: results: Paginated list of work items. total_count: True DB total, not page-bounded - use for counts. next_cursor: Cursor for the next page. prev_cursor: Cursor for the previous page.

Count work items across the workspace with optional grouping.

Use this for analytics - "how many urgent items?", "distribution by state?" - without fetching full work item payloads.

Args: pql: PQL filter to scope the count (e.g. 'priority = "urgent"'). group_by: Dimension to group counts by. Supported values: state_id, state__group, priority, project_id, type_id, labels__id, assignees__id, issue_module__module_id, release_work_items__release_id, cycle_id, milestone_id, created_by, target_date, start_date. sub_group_by: Second dimension for nested grouping (requires group_by).

Returns: grouped_by: The group_by field used (null if none). sub_grouped_by: The sub_group_by field used (null if none). total_count: Total matching work items. grouped_counts: Dict of group_key → {count} or {count, sub_grouped_counts} when sub_group_by is set. Keys are UUIDs for FK fields, plain strings for priority/state__group, ISO dates for target_date/start_date, "None" for unset values.

Create a new work item.

Args: project_id: UUID of the project name: Work item name (required) assignees: List of user IDs to assign to the work item labels: List of label IDs to attach to the work item type_id: UUID of the work item type point: Story point value description_html: HTML description of the work item description_stripped: Plain text description. Convenience only - it is wrapped into HTML and stored as description_html (Plane derives description_stripped server-side). Ignored if description_html is set. priority: Priority level (urgent, high, medium, low, none) start_date: Start date (ISO 8601 format) target_date: Target/end date (ISO 8601 format) sort_order: Sort order value is_draft: Whether the work item is a draft external_source: External system source name external_id: External system identifier parent: UUID of the parent work item state: UUID of the state estimate_point: Estimate point value type: Work item type identifier

Returns: Created WorkItem object

Retrieve a work item by ID.

Args: project_id: UUID of the project work_item_id: UUID of the work item expand: Comma-separated fields to expand (e.g., "assignees,labels,state") fields: Comma-separated fields to include in response external_id: External system identifier for filtering external_source: External system source name for filtering order_by: Field to order results by

Returns: WorkItemDetail object with expanded relationships

Retrieve a work item by its full identifier (project prefix + sequence number).

The identifier must be in PROJECT-N format where PROJECT is the project's identifier string and N is the sequence number. Both parts are required.

Valid sparse fields values include: id, name, sequence_id, priority, state, project, workspace, parent, assignees, labels, type_id, start_date, target_date, created_at, updated_at, created_by, updated_by, is_draft, external_source, external_id, estimate_point. Use project (not project_id) to get the project UUID.

If you need the project UUID from a short identifier like "SHO", use list_projects() instead - it returns id and identifier for every project.

Args: work_item_identifier: Full work item identifier in PROJECT-N format expand: Comma-separated fields to expand (e.g., "assignees,labels,state") fields: Comma-separated sparse fieldset (see valid values above) external_id: External system identifier for filtering external_source: External system source name for filtering order_by: Field to order results by

Returns: WorkItemDetail object with expanded relationships

Update a work item by ID.

Args: project_id: UUID of the project work_item_id: UUID of the work item name: Work item name assignees: List of user IDs to assign to the work item labels: List of label IDs to attach to the work item type_id: UUID of the work item type point: Story point value description_html: HTML description of the work item description_stripped: Plain text description. Convenience only - it is wrapped into HTML and stored as description_html (Plane derives description_stripped server-side). Ignored if description_html is set. priority: Priority level (urgent, high, medium, low, none) start_date: Start date (ISO 8601 format) target_date: Target/end date (ISO 8601 format) sort_order: Sort order value is_draft: Whether the work item is a draft external_source: External system source name external_id: External system identifier parent: UUID of the parent work item state: UUID of the state estimate_point: Estimate point value type: Work item type identifier

Returns: Updated WorkItem object

Delete a work item by ID.

Args: project_id: UUID of the project work_item_id: UUID of the work item

Add or remove a single assignee on a work item without replacing the full list.

Provide add_user_id, remove_user_id, or both. If both are given the removal is applied first, then the addition. Already-assigned users in add_user_id are silently skipped.

Args: project_id: UUID of the project work_item_id: UUID of the work item add_user_id: UUID of the user to add as assignee remove_user_id: UUID of the user to remove from assignees

Returns: Updated WorkItem object

Add or remove a single label on a work item without replacing the full list.

Provide add_label_id, remove_label_id, or both. If both are given the removal is applied first, then the addition. Already-attached labels in add_label_id are silently skipped.

Args: project_id: UUID of the project work_item_id: UUID of the work item add_label_id: UUID of the label to add remove_label_id: UUID of the label to remove

Returns: Updated WorkItem object

List archived work items in a project with optional PQL filtering.

Args: project_id: UUID of the project pql: PQL filter expression. Omit to list all archived items. order_by: Field to sort by; prefix with - for descending (default -archived_at). per_page: Results per page, 1-100 (default 100). cursor: Pagination cursor from a previous response's next_cursor. expand: Comma-separated related fields to expand. fields: Comma-separated sparse fieldset.

Returns: Paginated envelope with results, total_count, next_cursor, prev_cursor.

Archive or unarchive a work item.

Only work items in a completed or cancelled state can be archived. Archived work items no longer appear in active work item lists.

Args: project_id: UUID of the project work_item_id: UUID of the work item archive: True to archive the work item, False to unarchive it

Search work items by text across a workspace.

Matches on work item name, sequence id, and project identifier (not description). For structured filtering (priority, state, assignee, dates, etc.) use list_work_items with a PQL expression.

Args: query: Free-text string matched against name, sequence id, and project identifier expand: Comma-separated list of related fields to expand in response fields: Comma-separated list of fields to include in response external_id: External system identifier for filtering external_source: External system source name for filtering order_by: Field to order results by. Prefix with '-' for descending

Returns: WorkItemSearch object containing search results

List all states in a project.

Args: project_id: UUID of the project params: Optional query parameters as a dictionary

Returns: List of State objects

Create a new state.

Args: project_id: UUID of the project name: State name color: State color (hex color code) description: State description sequence: State sequence order group: State group (e.g., backlog, unstarted, started, completed, cancelled) is_triage: Whether this is a triage state default: Whether this is the default state external_source: External system source name external_id: External system identifier

Returns: Created State object

Retrieve a state by ID.

Args: project_id: UUID of the project state_id: UUID of the state

Returns: State object

Update a state by ID.

Args: project_id: UUID of the project state_id: UUID of the state name: State name color: State color (hex color code) description: State description sequence: State sequence order group: State group (e.g., backlog, unstarted, started, completed, cancelled) is_triage: Whether this is a triage state default: Whether this is the default state external_source: External system source name external_id: External system identifier

Returns: Updated State object

Delete a state by ID.

Args: project_id: UUID of the project state_id: UUID of the state

List all labels in a project.

Args: project_id: UUID of the project params: Optional query parameters as a dictionary

Returns: List of Label objects

Create a new label.

Args: project_id: UUID of the project name: Label name color: Label color (hex color code) description: Label description parent: UUID of the parent label (for nested labels) sort_order: Sort order for the label external_source: External system source name external_id: External system identifier

Returns: Created Label object

Retrieve a label by ID.

Args: project_id: UUID of the project label_id: UUID of the label

Returns: Label object

Update a label by ID.

Args: project_id: UUID of the project label_id: UUID of the label name: Label name color: Label color (hex color code) description: Label description parent: UUID of the parent label (for nested labels) sort_order: Sort order for the label external_source: External system source name external_id: External system identifier

Returns: Updated Label object

Delete a label by ID.

Args: project_id: UUID of the project label_id: UUID of the label

List cycles in a project. Active (non-archived) cycles by default.

Args: project_id: UUID of the project archived: Set True to list archived cycles instead of active ones. status: Filter active cycles by status - "current" (running now), "upcoming" (starts later), "completed" (ended), "draft" (no dates), or "incomplete" (not yet finished). Ignored when archived is True. cursor: Pagination cursor from a previous response's next_cursor (form "{per_page}:{page}:{offset}"). Omit for the first page. per_page: Number of results per page (1-1000, default and max 1000). order_by: Field to order results by. Prefix with '-' for descending.

Returns: Paginated envelope: results (lite cycles) + total_count, next_cursor, next_page_results.

Create a new cycle.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project name: Cycle name owned_by: UUID of the user who owns the cycle description: Cycle description start_date: Cycle start date (ISO 8601 format) end_date: Cycle end date (ISO 8601 format) external_source: External system source name external_id: External system identifier timezone: Cycle timezone

Returns: Created Cycle object

Retrieve a cycle by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the cycle

Returns: Cycle object

Update a cycle by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the cycle name: Cycle name description: Cycle description start_date: Cycle start date (ISO 8601 format) end_date: Cycle end date (ISO 8601 format) owned_by: UUID of the user who owns the cycle external_source: External system source name external_id: External system identifier timezone: Cycle timezone

Returns: Updated Cycle object

Delete a cycle by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the cycle

Add or remove work items on a cycle in a single call.

At least one of add_ids or remove_ids must be provided.

Args: project_id: UUID of the project cycle_id: UUID of the cycle add_ids: UUIDs of work items to add to the cycle remove_ids: UUIDs of work items to remove from the cycle

List work items in a cycle with optional PQL filtering.

Args: project_id: UUID of the project cycle_id: UUID of the cycle pql: PQL filter expression. See field description for syntax. Omit to list all items in the cycle. order_by: Field to sort by; prefix with - for descending. per_page: Results per page, 1-100 (default 25). cursor: Pagination cursor from a previous response's next_cursor. expand: Comma-separated related fields to expand. fields: Comma-separated sparse fieldset.

Returns: Paginated envelope with results, total_count, next_cursor, prev_cursor.

Transfer work items from one cycle to another.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project cycle_id: UUID of the source cycle new_cycle_id: UUID of the target cycle to transfer issues to

Archive or unarchive a cycle.

Plane requires the cycle end_date to be in the past before archiving. When archive=True, this tool automatically sets end_date to today if the cycle is still active (end_date is missing or in the future), then archives it.

Args: project_id: UUID of the project cycle_id: UUID of the cycle archive: True to archive the cycle, False to unarchive it

Returns: True if the operation completed successfully

Complete (close) a cycle by setting its end date to today.

Plane has no explicit "complete" action - a cycle is considered complete when its end_date is in the past. This tool sets end_date to today, effectively closing the cycle.

Args: project_id: UUID of the project cycle_id: UUID of the cycle to complete

Returns: Updated Cycle object

List modules in a project.

Args: project_id: UUID of the project archived: Set True to list archived modules instead of active ones. cursor: Pagination cursor from a previous response's next_cursor (form "{per_page}:{page}:{offset}"). Omit for the first page. per_page: Number of results per page (1-1000, default and max 1000). order_by: Field to order results by. Prefix with '-' for descending.

Returns: Paginated envelope: results (lite modules) + total_count, next_cursor, next_page_results.

Create a new module.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project name: Module name description: Module description start_date: Module start date (ISO 8601 format) target_date: Module target/end date (ISO 8601 format) status: Module status (backlog, planned, in-progress, paused, completed, cancelled) lead: UUID of the user who leads the module members: List of user IDs who are members of the module external_source: External system source name external_id: External system identifier

Returns: Created Module object

Retrieve a module by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project module_id: UUID of the module

Returns: Module object

Update a module by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project module_id: UUID of the module name: Module name description: Module description start_date: Module start date (ISO 8601 format) target_date: Module target/end date (ISO 8601 format) status: Module status (backlog, planned, in-progress, paused, completed, cancelled) lead: UUID of the user who leads the module members: List of user IDs who are members of the module external_source: External system source name external_id: External system identifier

Returns: Updated Module object

Delete a module by ID.

Args: workspace_slug: The workspace slug identifier project_id: UUID of the project module_id: UUID of the module

Add or remove work items on a module in a single call.

At least one of add_ids or remove_ids must be provided.

Args: project_id: UUID of the project module_id: UUID of the module add_ids: UUIDs of work items to add to the module remove_ids: UUIDs of work items to remove from the module

List work items in a module with optional PQL filtering.

Args: project_id: UUID of the project module_id: UUID of the module pql: PQL filter expression. See field description for syntax. Omit to list all items in the module. order_by: Field to sort by; prefix with - for descending. per_page: Results per page, 1-100 (default 25). cursor: Pagination cursor from a previous response's next_cursor. expand: Comma-separated related fields to expand. fields: Comma-separated sparse fieldset.

Returns: Paginated envelope with results, total_count, next_cursor, prev_cursor.

Archive or unarchive a module.

Args: project_id: UUID of the project module_id: UUID of the module archive: True to archive the module, False to unarchive it

Get current user information.

Returns: UserLite object containing current user information

List members of the current workspace (filterable, paginated).

Optional filters first_name/last_name/email/display_name (case-insensitive contains), role_slug (exact), is_active, is_bot - combined with AND.

Args: cursor: Prior response's next_cursor; omit for first page. per_page: Results per page (1-1000, default 100). order_by: Sort field; prefix '-' for descending.

Returns: Paginated envelope: results (members incl. role, role_slug, is_active, is_bot) + total_count, next_cursor, next_page_results.

Get feature flags.

Returns a project's features if project_id is given, otherwise the workspace's features.

Args: project_id: UUID of the project. Omit for workspace features.

Returns: ProjectFeature when project_id is given, otherwise WorkspaceFeature.

Update features of the current workspace.

Args: project_grouping: Enable/disable project grouping feature initiatives: Enable/disable initiatives feature teams: Enable/disable teams feature customers: Enable/disable customers feature wiki: Enable/disable wiki feature pi: Enable/disable PI (Program Increment) feature

Returns: Updated WorkspaceFeature object

Get edition/version info and known API limitations of the connected Plane instance.

Use this to understand up-front which tool families are unavailable (e.g. pages, epics/work-item types, initiatives, estimates and milestones on Community Edition) instead of discovering them through 404 errors.

Returns: Dict with base_url, edition (e.g. "PLANE_COMMUNITY"), version, compat_reference, and - for Community Edition - unavailable_features.

List the tool groups (toolsets) this server knows and which are active.

Toolsets are selected with the PLANE_TOOLSETS env var (comma-separated, or "all"). A client that only needs a subset can set it to load fewer tool definitions into its context window.

Returns: Dict with active (toolset names currently registered) and available (every toolset name the server supports).

List comments for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item params: Optional query parameters as a dictionary

Returns: List of WorkItemComment objects

Retrieve a specific comment for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item comment_id: UUID of the comment

Returns: WorkItemComment object

Create a comment for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item comment_html: Comment content in HTML format comment_json: Comment content in JSON format access: Access level for the comment (INTERNAL or EXTERNAL) external_source: External system source name external_id: External system identifier

Returns: Created WorkItemComment object

Update a comment for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item comment_id: UUID of the comment comment_html: Comment content in HTML format comment_json: Comment content in JSON format access: Access level for the comment (INTERNAL or EXTERNAL) external_source: External system source name external_id: External system identifier

Returns: Updated WorkItemComment object

Delete a comment for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item comment_id: UUID of the comment

List links for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item params: Optional query parameters as a dictionary

Returns: List of WorkItemLink objects

Retrieve a specific link for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item link_id: UUID of the link

Returns: WorkItemLink object

Create a link for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item url: URL of the link

Returns: Created WorkItemLink object

Update a link for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item link_id: UUID of the link url: Updated URL of the link

Returns: Updated WorkItemLink object

Delete a link for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item link_id: UUID of the link

List all attachments for a work item.

Returns metadata for each attachment. To get a downloadable link for a specific attachment, use get_work_item_attachment_download_url.

Args: project_id: UUID of the project work_item_id: UUID of the work item

Returns: List of attachments, each with: id, name, size, content_type, created_at, created_by.

Get a presigned download URL for a work item attachment.

Returns a time-limited URL (typically valid ~1 hour) that can be opened directly in a browser or downloaded with any HTTP client - no Plane authentication required on the URL itself.

Use list_work_item_attachments first to get attachment IDs and names.

Args: project_id: UUID of the project work_item_id: UUID of the work item attachment_id: UUID of the attachment

Returns: Dict with: download_url (presigned S3 URL), attachment_id, name.

Fetch a file from a public URL and attach it to a work item.

The MCP server downloads the file server-side and uploads it to Plane via the standard three-step presigned S3 flow. The source URL must be publicly accessible without authentication and must not resolve to a private/internal network address.

Args: project_id: UUID of the project work_item_id: UUID of the work item url: Publicly accessible URL of the file to attach (e.g. a GitHub raw URL, public S3 link, or direct download link) name: Override the filename. Defaults to the filename in the URL path.

Returns: Created attachment metadata: id, name, size, content_type.

Delete an attachment from a work item.

Use list_work_item_attachments to get the attachment_id.

Args: project_id: UUID of the project work_item_id: UUID of the work item attachment_id: UUID of the attachment to delete

Fetch an attachment's content so the LLM can read or analyze it.

Supported file types: Images (returned as vision-readable image, max 5 MB): PNG, JPEG, GIF, WEBP Text (returned as a string, max 1 MB): TXT, MD, CSV, HTML, XML, YAML, JSON

Not supported (use get_work_item_attachment_download_url instead): PDF - requires a text-extraction library (not installed) DOCX/XLSX/PPTX - binary Office formats, require extraction Audio / Video - non-textual binary formats Generic binary - executables, archives, etc.

Args: project_id: UUID of the project work_item_id: UUID of the work item attachment_id: UUID of the attachment

Returns: Image object for image files, plain string for text files.

Raises: ValueError: If the file type is unsupported or the file exceeds the size limit for its category.

List activities for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item params: Optional query parameters as a dictionary

Returns: List of WorkItemActivity objects

Retrieve a specific activity for a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item activity_id: UUID of the activity

Returns: WorkItemActivity object

List pages.

Lists a project's pages if project_id is given, otherwise workspace-level pages. The list contains metadata only - description_html is null here by design; fetch a page's content with retrieve_page.

Args: project_id: UUID of the project. Omit to list workspace pages. params: Optional query parameters as a dictionary (e.g., per_page, cursor)

Returns: List of Page objects (metadata only, no page content)

Link a page to a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item page_id: UUID of the page to link

Returns: WorkItemPage link object

List all pages linked to a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item

Returns: List of WorkItemPage link objects

Remove a page link from a work item.

Args: project_id: UUID of the project work_item_id: UUID of the work item work_item_page_id: UUID of the work item page link (not the page ID)

Retrieve a page by ID, including its content (description_html).

Retrieves a project page if project_id is given, otherwise a workspace page. Page bodies can be large; pass max_length (or set the server-side PLANE_PAGES_MAX_CONTENT_LENGTH env default) to bound the returned content.

Args: page_id: UUID of the page project_id: UUID of the project. Omit for a workspace page. max_length: Maximum number of characters of content to return. When the content is longer, the response carries content_truncated=true and total_content_length with the full size.

Returns: Page object; when truncation applies, a dict with the page fields plus content_truncated and total_content_length.

Search pages by title (and optionally content) with a simple case-insensitive substring match.

Plane has no server-side page search API, so this filters the page list client-side. With search_content=true each candidate page's content is fetched individually (capped at 30 pages) - slower but matches body text.

Args: query: Text to look for (case-insensitive substring). project_id: UUID of the project. Omit to search workspace pages (workspace pages are unavailable on Community Edition). search_content: Also search inside page content, not just titles. max_results: Maximum number of matches to return (default 20).

Returns: List of matches: id, name, project_id, match_field ("name" or "content") and a snippet of the surrounding text.

Create a page.

Creates a project page if project_id is given, otherwise a workspace-level page.

Args: name: Page name description_html: Page content in HTML format project_id: UUID of the project. Omit to create a workspace page. access: Access level for the page (integer) color: Page color is_locked: Whether the page is locked archived_at: Archive timestamp (ISO 8601 format) view_props: View properties dictionary logo_props: Logo properties dictionary external_id: External system identifier external_source: External system source name

Returns: Created Page object

List work item types. Omit project_id for workspace-level types.

Each result's id is the work_item_type_id needed by list_work_item_properties to look up custom property and option UUIDs for PQL cf[] filters.

Create a new work item type.

To get a usable type for a project (e.g. "Epic"), prefer resolve_work_item_type, which finds-or-creates at the correct scope and never duplicates.

Args: name: Work item type name project_id: UUID of the project. Omit for workspace-level type. description: Work item type description project_ids: List of project IDs this type applies to is_active: Whether the type is active external_source: External system source name external_id: External system identifier

Returns: Created WorkItemType object

Bulk-link workspace-level work item types to a project.

Imports one or more workspace-scoped work item types into a project so that they become available for use within that project.

For the common case of getting one named type usable in a project, prefer resolve_work_item_type, which finds-or-creates and imports in one step.

Args: project_id: UUID of the project work_item_type_ids: List of workspace-level work item type UUIDs to import

Find a work item type by name for a project, create it if missing, and guarantee it is usable inside that project. Use this to resolve the type_id for a typed work item such as an "Epic" or "Initiative" before calling create_work_item(type_id=...).

Handles workspace-level and project-level work item types automatically, so the caller never has to decide which mode the workspace is in:

• If the workspace owns work item types, the type is found (or created) at the workspace level and imported into the project. Project-level creation is blocked in this mode, so importing is the only valid path.

• Otherwise the type is found (or created) at the project level, enabling the project's work item types feature first if it is off.

Matching is exact (case-sensitive, whitespace-stripped); an existing type is never duplicated.

Prefer this over manually combining get_workspace_features, list_work_item_types, create_work_item_type, and import_work_item_types_to_project - it does all of that deterministically.

Args: project_id: UUID of the project the type must be usable in name: Work item type name, e.g. "Epic" or "Initiative"

Returns: The WorkItemType. Its id is the type_id for create_work_item.

Retrieve a work item type by ID.

Args: work_item_type_id: UUID of the work item type project_id: UUID of the project. Omit for workspace scope.

Returns: WorkItemType object

Update a work item type by ID.

Args: work_item_type_id: UUID of the work item type project_id: UUID of the project. Omit for workspace scope. name: Work item type name description: Work item type description project_ids: List of project IDs this type applies to is_active: Whether the type is active external_source: External system source name external_id: External system identifier

Returns: Updated WorkItemType object

Delete a work item type by ID.

Args: work_item_type_id: UUID of the work item type project_id: UUID of the project. Omit for workspace scope.

List custom work item properties.

Scope resolution (highest priority first):

• no args → ALL workspace-level properties (one API call)

• work_item_type_id only → workspace-level properties linked to that type

• project_id only → all properties in that project (any type)

• project_id + work_item_type_id → properties linked to that type in that project, falling back to project-flat then workspace if empty

For PQL filtering by name, prefer calling with NO args - one workspace-wide fetch beats iterating every work item type. Each result includes the display_name you can match in-memory before composing cf["<id>"] in PQL.

Each result includes:

• id: property UUID - use as cf[""] in PQL filters

• display_name: user-facing label (e.g. "Fed", "Acceptance Criteria")

• property_type: TEXT | OPTION | DECIMAL | BOOLEAN | DATETIME | RELATION | URL | EMAIL

• options: for OPTION type, each option has id + name; use option id in PQL

PQL workflow for filtering by custom property (efficient path):

1. list_work_item_properties() → all workspace properties, one call

2. find the property by display_name in-memory → property.id

3. list_work_items(pql='cf["<property.id>"] = "<option.id>"')

Create a new work item property.

Scope resolution:

• project_id + work_item_type_id → type-scoped project property (legacy)

• project_id only → project-level property (not yet linked to a type)

• neither → workspace-level property

Args: display_name: Display name for the property property_type: TEXT | DATETIME | DECIMAL | BOOLEAN | OPTION | RELATION | URL | EMAIL | FILE | FORMULA project_id: UUID of the project. Omit for workspace-level property. work_item_type_id: UUID of the work item type - omit to create at project level relation_type: ISSUE | USER - required when property_type=RELATION description: Property description is_required: Whether the property is required default_value: Default value(s) for the property settings: Required for TEXT/DATETIME. TEXT: {"display_format": "single-line"|"multi-line"|"readonly"} DATETIME: {"display_format": "MMM dd, yyyy"|"dd/MM/yyyy"|"MM/dd/yyyy"|"yyyy/MM/dd"} is_active: Whether the property is active is_multi: Whether the property supports multiple values validation_rules: Validation rules dictionary external_source: External system source name external_id: External system identifier options: List of {name, color?, is_default?} dicts - for OPTION type

Returns: Created WorkItemProperty object

Retrieve a work item property by ID.

Args: work_item_property_id: UUID of the property project_id: UUID of the project. Omit for workspace scope. work_item_type_id: UUID of the work item type - omit to use project-level endpoint

Returns: WorkItemProperty object

Update a work item property by ID.

Args: work_item_property_id: UUID of the property project_id: UUID of the project. Omit for workspace scope. work_item_type_id: UUID of the work item type - required when project_id is provided display_name: Display name for the property property_type: TEXT | DATETIME | DECIMAL | BOOLEAN | OPTION | RELATION | URL | EMAIL | FILE | FORMULA relation_type: ISSUE | USER - required when updating to RELATION description: Property description is_required: Whether the property is required default_value: Default value(s) for the property settings: Required when changing type to TEXT/DATETIME. TEXT: {"display_format": "single-line"|"multi-line"|"readonly"} DATETIME: {"display_format": "MMM dd, yyyy"|"dd/MM/yyyy"|"MM/dd/yyyy"|"yyyy/MM/dd"} is_active: Whether the property is active is_multi: Whether the property supports multiple values validation_rules: Validation rules dictionary external_source: External system source name external_id: External system identifier

Returns: Updated WorkItemProperty object

Delete a work item property by ID.

Args: work_item_property_id: UUID of the property project_id: UUID of the project. Omit for workspace scope. work_item_type_id: UUID of the work item type - omit to use project-level endpoint