Get project metadata
get_project_metadataRetrieve valid OpenProject metadata: types, statuses, priorities, versions, categories, activities. Use before creating, updating, or filtering to get correct IDs and avoid errors.
Instructions
List the ids and names that are actually valid on this instance.
This is the one-call answer to "what do I pass for type / status / priority / version / category / activity". Call it before any create or update, before filtering by ids, and whenever a write fails with an allowed-values error. Nothing here is hardcoded — priority ids and activity ids differ per instance.
Without project_id returns the global types, statuses, priorities and
roles. With project_id the types list narrows to the ones enabled in that
project and versions, categories and time_entry_activities are filled in.
Every row is {id, name} plus its flags: statuses[].is_closed is the
authoritative done marker (never classify by status name — it is localized),
types[].is_milestone tells you the type takes a single date, and
priorities[].is_default / time_entry_activities[].is_default say what you get
by omitting the field.
Pitfalls: results are cached (default 300 s) — pass refresh=true after an admin
change. Time-entry activities are read from the time-entry form, so if the time
tracking module is off or you lack permission the list comes back empty with a note
in notes rather than an error (check notes).
For the writable fields and custom fields of one project+type combination use
get_work_package_schema; for project ids themselves use list_projects.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | Bypass the metadata cache. Use it right after an administrator added a type, status, version or category; otherwise leave it false. | |
| project_id | No | Numeric project id or URL identifier. Omit for the instance-global sets (types, statuses, priorities, roles) — cross-project filtering never needs an arbitrary project. Supply it to additionally get this project's types, versions, categories and time-entry activities. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Degradation notes: modules off, permissions missing. | |
| roles | No | All membership roles. | |
| types | No | Work-package types; scoped to the project when project_id was given. | |
| statuses | No | All statuses, each with is_closed. | |
| versions | No | Project versions/sprints; null unless project_id was given. | |
| categories | No | Project categories; null unless project_id was given. | |
| priorities | No | All priorities. | |
| project_id | No | The project this was scoped to; null for the global sets. | |
| time_entry_activities | No | Activities log_time accepts here; null unless project_id was given. |