Plane

Plane Query Language (PQL) syntax reference. Call this before composing a `pql` filter for the workitem list, list_archived or count actions. Actions: read (no required params; optional detail) -- this tool has no action parameter. detail 'full' gives operators, functions, common mistakes and worked examples; 'brief' gives the compact field and operator quick reference.

get_pql_reference

Collections grouping workspace pages. Actions: list (no required params); retrieve (collection_id); create (name; optional access) -- access is fixed at creation and cannot be changed afterwards; update (collection_id; optional name, sort_order) -- only the fields you pass are changed; delete (collection_id; optional archive_pages) -- the pages survive; archive_pages defaults to true, pass false to leave them unfiled instead; list_pages (collection_id; optional search, parent_id, cursor, per_page); search_pages (collection_id; optional search) -- pages not yet in this collection, to pick ids for add_pages; add_pages (collection_id, page_ids) -- files existing pages; use page create to make new ones; remove_page (collection_id, page_collection_id) -- page_collection_id is the membership id from list_pages, not the page id; the page itself is kept; list_members (collection_id); add_member (collection_id, user_id, member_access); update_member (collection_id, collection_member_id, member_access); remove_member (collection_id, collection_member_id) -- collection_member_id is the membership id from list_members, not the user id. access is one of: public, private -- a private collection is visible only to its members, and the level cannot be changed once the collection exists. member_access is one of: view, comment, edit and is a separate scale from access. Collections group workspace pages only; a project's pages cannot be filed in one. To file or move a page, use `page set_collection` -- it works out which collection holds the page for you, so it needs no membership id.

collection

Pages at workspace or project scope. Actions: list (no required params; optional project_id, cursor, per_page) -- workspace pages unless project_id is given; retrieve (page_id; optional project_id); create (name, description_html; optional project_id, parent_id, collection_id, access, color, is_locked, external_source, external_id) -- parent_id nests the new page under an existing one; collection_id files it. Pass one or the other, never both; update (page_id; optional project_id, name, description_html) -- pass name, description_html, or both; description_html replaces the whole body, so retrieve the page first when editing part of it; a locked or archived page is refused; archive (page_id; optional project_id, archive) -- archive defaults to true; pass archive=false to restore; delete (page_id; optional project_id) -- requires the page to be archived first; set_collection (page_id, collection_id) -- files a page into a collection, or moves it out of the one it is in; workspace pages only, and collection_id comes from the collection tool; list_workitem_pages (project_id, workitem_id); attach_to_workitem (project_id, workitem_id, page_id); detach_from_workitem (project_id, workitem_id, workitem_page_id) -- workitem_page_id is the link id from list_workitem_pages, not the page id. description_html is the page body as HTML. access is the page access level. update changes only the fields you pass. A page must be archived before it can be deleted. Omit project_id to work with workspace-level pages. A page's parent is fixed at creation -- pass parent_id to create to build a hierarchy, since nothing can reparent it afterwards. list and retrieve both report a page's parent_id and the collection_id it is filed in, so neither needs looking up. Collections themselves live in the collection tool; here, create files a new page into one and set_collection files or moves an existing page.

page

A project's estimate system and its points. Actions: retrieve (project_id) -- a project has at most one estimate; create (project_id, name; optional type, description, last_used, external_source, external_id) -- creates the estimate only; add its values afterwards with create_points; update (project_id; optional name, description, external_source, external_id); delete (project_id); link (project_id, estimate_id) -- makes that estimate the project's active one; list_points (project_id, estimate_id); create_points (project_id, estimate_id, points); update_point (project_id, estimate_id, estimate_point_id; optional value, key, description, external_source, external_id); delete_point (project_id, estimate_id, estimate_point_id). type is one of: categories, points, time. A point's `value` is its display label ("5", "XL") and its `key` is the sort order. points takes a JSON array such as [{"value": "1", "key": 0}]. To set a work item's estimate: retrieve to get the estimate_id, list_points to see the available values, then pass the chosen point's id to `workitem update` as estimate_point.

project_estimate

Projects in a workspace. Actions: list (no required params; optional cursor, per_page, order_by) -- trimmed fields; use retrieve for full detail; retrieve (project_id); create (name, identifier; optional description, description_html, project_lead, default_assignee, emoji, cover_image, timezone, archive_in, close_in, external_source, external_id); update (project_id; optional name, description, description_html, identifier, project_lead, default_assignee, emoji, cover_image, network, timezone, archive_in, close_in, default_state, estimate, is_time_tracking_enabled, external_source, external_id) -- only the fields you pass are changed; delete (project_id); archive (project_id); unarchive (project_id); worklog_summary (project_id); get_features (project_id); update_features (project_id; optional modules, cycles, views, pages, intakes, workitem_types, epics, parallel_cycles, project_updates, workflows) -- toggles project features on or off. identifier is the short work item prefix, such as ENG. network is 0 for secret or 2 for public. project_lead and default_assignee are member ids -- get them from `member list_workspace`. Feature toggles are booleans; omitted ones are left as they are.

project

Release labels, workspace palette and per release. Actions: list (no required params; optional release_id, cursor, per_page) -- the workspace palette unless release_id is given; create (name; optional color, sort_order) -- adds to the workspace palette; update (label_id; optional name, color, sort_order); delete (label_id) -- removes it from the palette entirely; attach (release_id, label_ids) -- returns nothing, read back with list; detach (release_id, label_ids) -- returns nothing, read back with list. color is a hex code such as #4E5355. label_ids takes palette label ids. Detaching a label leaves it in the palette; delete removes it for everyone.

release_label

Release tags (version markers). Actions: list (no required params; optional cursor, per_page); retrieve (tag_id); create (version; optional description, commit_hash, git_tag); update (tag_id; optional version, description, commit_hash, git_tag) -- only the fields you pass are changed; delete (tag_id). version is a version string such as "v1.2.0". A tag id is what release takes as tag_id.

release_tag

Releases in the workspace. Actions: list (no required params; optional cursor, per_page); retrieve (release_id); create (name; optional description_html, status, release_date, target_date, tag_id, lead_id, is_prerelease, external_source, external_id); update (release_id; optional name, description_html, status, release_date, target_date, tag_id, lead_id, is_prerelease) -- only the fields you pass are changed; delete (release_id); get_changelog (release_id); update_changelog (release_id; optional description_html, description_stripped); list_workitems (release_id; optional cursor, per_page); manage_workitems (release_id; optional add_ids, remove_ids) -- pass at least one of add_ids or remove_ids; returns nothing, read back with list_workitems. status is one of: unreleased, released, cancelled, defaulting to unreleased. release_date is what the Plane UI labels "Target date" (YYYY-MM-DD); target_date is a separate stored date that the UI does not show. tag_id comes from `release_tag list`, lead_id from `member list_workspace`. For the changelog pass description_html, or description_stripped for plain text. A changelog is created empty with the release, so get_changelog always returns one.

release

Reusable templates for work items, pages and projects. Actions: list (kind; optional project_id); create (kind, name, template_data; optional project_id, description); update (kind, template_id; optional project_id, name, description, template_data) -- only the fields you pass are changed; delete (kind, template_id; optional project_id). kind is one of: workitem, page, project. project_id chooses the scope a write lands in; omit it for the workspace, which is also the only scope a project kind can live at. For a workitem or page kind, listing without project_id is the wider view: it returns a project's templates as well as the workspace's own, told apart by a non-null project. Pass project_id to list one project's alone. template_data is a JSON object holding what gets templated -- for a work item template, the fields a work item created from it starts with, such as {"name": "Spec", "description_html": "<p>Context / Acceptance criteria</p>", "priority": "medium"}. update merges it into what is there rather than replacing it, so pass only what changes. description is the template's own summary, not the templated body.

template

Change history for a work item. Actions: list (project_id, workitem_id; optional cursor, per_page); retrieve (project_id, workitem_id, activity_id).

workitem_activity

Files attached to a work item. Actions: list (project_id, workitem_id); read (project_id, workitem_id, attachment_id) -- returns images and text inline; use download_url for anything else; download_url (project_id, workitem_id, attachment_id); upload_from_url (project_id, workitem_id, url; optional name); delete (project_id, workitem_id, attachment_id). read supports PNG/JPEG/GIF/WEBP up to 5 MB and TXT/MD/CSV/HTML/XML/YAML/JSON up to 1 MB. Get attachment_id from the list action. upload_from_url fetches the file server-side, so the URL must be reachable without authentication and must not resolve to a private address.

workitem_attachment

Comments on a work item. Actions: list (project_id, workitem_id; optional cursor, per_page); retrieve (project_id, workitem_id, comment_id); create (project_id, workitem_id, comment_html; optional access, external_source, external_id); update (project_id, workitem_id, comment_id; optional comment_html, access, external_source, external_id); delete (project_id, workitem_id, comment_id). comment_html is HTML, e.g. '<p>Looks good.</p>'. access is INTERNAL or EXTERNAL.

workitem_comment

External links attached to a work item. Actions: list (project_id, workitem_id; optional cursor, per_page); retrieve (project_id, workitem_id, link_id); create (project_id, workitem_id, url); update (project_id, workitem_id, link_id, url); delete (project_id, workitem_id, link_id).

workitem_link

Custom work item properties and their options. Actions: list (no required params; optional project_id, workitem_type_id, cursor, per_page) -- no ids lists every workspace property in one call -- the fast path for PQL; retrieve (workitem_property_id; optional project_id, workitem_type_id); create (display_name, property_type; optional project_id, workitem_type_id, description, relation_type, is_required, is_multi, is_active, default_value, options, display_format, external_source, external_id); update (workitem_property_id; optional project_id, workitem_type_id, display_name, property_type, description, relation_type, is_required, is_multi, is_active, default_value, display_format, external_source, external_id) -- only the fields you pass are changed; delete (workitem_property_id; optional project_id, workitem_type_id); manage_type_properties (workitem_type_id; optional project_id, attach_ids, detach_ids) -- omit project_id where the workspace owns types; detach removes the association only, it does not delete the property; list_options (property_id; optional project_id); retrieve_option (property_id, option_id; optional project_id); create_option (property_id, name; optional project_id, description, color, is_default, external_source, external_id); update_option (property_id, option_id; optional project_id, name, description, color, is_default, external_source, external_id); delete_option (property_id, option_id; optional project_id); get_value (project_id, workitem_id, property_id); set_value (project_id, workitem_id, property_id, value; optional external_source, external_id) -- upsert; for a multi-value property this replaces every existing value; delete_value (project_id, workitem_id, property_id). property_type is one of: TEXT, DATETIME, DECIMAL, BOOLEAN, OPTION, RELATION, URL, EMAIL, FILE, FORMULA. relation_type (for RELATION properties) is one of: ISSUE, USER, RELEASE, RICH_TEXT. A property id is what goes in a PQL cf["<id>"] filter; for OPTION properties the value is an option id. options takes a JSON array of {"name", "color", "is_default"} objects. display_format is required by TEXT (single-line, multi-line, readonly) and DATETIME (MMM dd, yyyy, dd/MM/yyyy, MM/dd/yyyy, yyyy/MM/dd) properties. A property lives with its type: where the workspace owns types, pass workitem_type_id without project_id and it is created in the workspace catalogue and associated for you. list resolves scope in this order: project_id + workitem_type_id is type-scoped (falling back to project-flat then workspace when empty), project_id alone is every property in the project, and neither is every workspace property. To filter by property name in PQL, call list with no ids -- one workspace-wide fetch beats iterating types -- then match display_name in memory to get the id for a cf[] condition. The *_value actions read and write a property on one work item: pass value in the type the property expects -- TEXT/URL/EMAIL/FILE as a string; DATETIME as a YYYY-MM-DD or YYYY-MM-DD HH:MM:SS string; DECIMAL as a number; BOOLEAN as true or false; OPTION and RELATION as an option or record id string, or an array of them when the property is multi-value. Send the value's own type, not a stringified form: "007" stays the text 007, whereas 7 is the number.

workitem_property

Relations between work items, and the definitions that type them. Actions: list (project_id, workitem_id); create (project_id, workitem_id, workitem_ids; optional relation_type, relation_definition_id, relation_definition_label) -- pass relation_type for a dependency, or definition id + label for a custom relation; delete (project_id, workitem_id, related_workitem_id; optional is_dependency) -- removes one relation; dependencies and custom relations are independent, so is_dependency must match the kind that was created (default false); list_definitions (no required params; optional is_default, is_active); create_definition (name; optional outward, inward, is_active, color); update_definition (definition_id; optional name, outward, inward, is_active, color); delete_definition (definition_id). Call list_definitions first and match the user's wording to an entry. A built_in_dependencies value (blocking, blocked_by, start_before, start_after, finish_before, finish_after) goes in relation_type; a custom definition needs its id in relation_definition_id and the matched outward or inward label in relation_definition_label, which sets direction.

workitem_relation

Work item types, at project or workspace scope. Actions: list (no required params; optional project_id, cursor, per_page) -- workspace scope when project_id is omitted; retrieve (workitem_type_id; optional project_id); resolve (project_id, name) -- finds or creates a named type usable in the project; never duplicates; create (name; optional project_id, description, project_ids, is_active, external_source, external_id); update (workitem_type_id; optional project_id, name, description, project_ids, is_active, external_source, external_id) -- only the fields you pass are changed; delete (workitem_type_id; optional project_id); import_to_project (project_id, workitem_type_ids) -- links workspace types to a project. Omit project_id to work at workspace scope. A type's id is the type_id for `workitem create` and the workitem_type_id for `workitem_property list`. Prefer resolve over create when you just need a usable type such as Epic or Initiative: it handles both modes, matches exactly (case-sensitive, whitespace-stripped) and never duplicates. Where the workspace owns the vocabulary, creating a type on a project is rejected and importing is the only valid path -- resolve does that for you.

workitem_type

Work items -- issues, tasks and epics. Actions: list (no required params; optional project_id, pql, order_by, per_page, cursor, expand, fields, external_id, external_source) -- omit project_id to search the whole workspace; list_archived (project_id; optional pql, order_by, per_page, cursor, expand, fields, external_id, external_source); retrieve (project_id, workitem_id; optional expand, fields, external_id, external_source, order_by); retrieve_by_identifier (workitem_identifier; optional expand, fields, external_id, external_source, order_by) -- identifier is PROJECT-N, e.g. ENG-42; search (query; optional expand, fields, external_id, external_source, order_by); count (no required params; optional project_id, pql, group_by, sub_group_by) -- counts the whole workspace unless project_id narrows it; create (project_id, name; optional assignees, labels, type_id, point, description_html, description_stripped, priority, start_date, target_date, sort_order, is_draft, parent, state, estimate_point, external_source, external_id); update (project_id, workitem_id; optional name, assignees, labels, type_id, point, description_html, description_stripped, priority, start_date, target_date, sort_order, is_draft, parent, state, estimate_point, external_source, external_id) -- only the fields you pass are changed; delete (project_id, workitem_id); archive (project_id, workitem_id; optional archive) -- archive defaults to true; pass archive=false to unarchive. Only completed or cancelled items can be archived; manage_assignee (project_id, workitem_id; optional add_user_id, remove_user_id) -- each takes one id or several; the list is merged, not replaced, and removals apply first; manage_label (project_id, workitem_id; optional add_label_id, remove_label_id) -- each takes one id or several; the list is merged, not replaced, and removals apply first. priority: urgent, high, medium, low, none. UUID fields (assignees, labels, state, parent, type_id) need UUIDs -- list the relevant resource first if you only have a name. description_stripped is plain text and is wrapped into HTML on save; description_html wins if both are given. fields is a sparse fieldset: use `project`, not project_id, and `description_html`, not description. count group_by and sub_group_by accept: 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. These are grouping keys only -- they are not PQL filter fields, and filtering on state__group is rejected.

workitem

Time logged against a work item. Actions: list (project_id, workitem_id; optional cursor, per_page); create (project_id, workitem_id, duration; optional description); update (project_id, workitem_id, work_log_id; optional duration, description); delete (project_id, workitem_id, work_log_id). duration is in minutes.

work_log

Workflow states within a project. Actions: list (no required params; optional project_id, cursor, per_page) -- workspace scope when project_id is omitted; retrieve (state_id; optional project_id); create (name, color; optional project_id, description, sequence, group, default, external_source, external_id) -- group is required at workspace scope; update (state_id; optional project_id, name, color, description, sequence, group, default) -- only the fields you pass are changed; delete (state_id; optional project_id). group is one of: backlog, unstarted, started, completed, cancelled. color is a hex code such as #EF4444. A project also has a triage state, but Plane owns it: it cannot be created here and is not listed, and Triage is a reserved name. Omit project_id to work with the workspace catalogue, which is where states live once the workspace owns them; sequence and default apply to a project's states only.

state

Workspace-level feature flags. Actions: get_features (no required params) -- feature flags for the current workspace; update_features (no required params; optional project_grouping, initiatives, teams, customers, wiki, pi) -- only the flags you pass are changed. For a project's feature flags use `project get_features` and `project update_features`.

workspace