List project phase definitions
list_project_phase_definitionsGet the instance-wide catalog of project phase definitions and gates. Use it to identify phase IDs and names for filtering projects by lifecycle phase.
Instructions
List the instance-global phase definitions — the vocabulary of the project life cycle.
Use it to learn which phases (Initiating, Planning, …) and gates this instance
defines, and to get the definition id or name that list_projects(in_phase=...)
accepts.
Returns the standard list envelope of {id, name, start_gate, start_gate_name, finish_gate, finish_gate_name} rows. Gates are the checkpoints a phase can begin
or end with; a definition without gates has both flags false.
Pitfalls: definitions are the instance-wide catalog, not any project's actual
phases — a project may deactivate phases or set no dates. Phase dates are not
exposed by the API at all. Requires OpenProject 16.1+ and the
view_project_phases permission in at least one project; older instances 404
(the error hint says so).
Cross-references: list_projects(in_phase=...) to find the projects a phase
covers today; get_project_phase for one project's phase record (its id comes
from a work package's project_phase).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | 1-based page number. | |
| page_size | No | Records per page (max 100); most instances define fewer than a page of phases. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sums | No | Present only when show_sums was requested. | |
| items | No | The page of results. | |
| notes | No | Degradation markers: capped aggregations, unavailable modules, … | |
| groups | No | Present only when group_by was requested. | |
| pagination | Yes | Total/page/page_size/has_more. |