Update project
update_projectUpdate an OpenProject project's name, description, status, visibility, parent, or archived state. Validated partial updates avoid overwriting unrelated fields.
Instructions
Change a project's name, description, visibility, parent, status or archived state.
Use it to record a status change with its explanation ("at_risk because the vendor
slipped"), to rename or re-parent a project, to publish it, or to archive it with
active=false. The change is validated through POST /projects/{id}/form first,
so rejected values come back as violations naming the attribute.
Only the parameters you pass are sent — omitted fields are never rewritten, so two
agents editing different fields do not clobber each other. Projects carry no
lockVersion upstream, so there is no version to echo and no lock parameter here.
Returns the updated project in the same shape as get_project.
Pitfalls: description and status_explanation REPLACE the stored text rather
than appending to it. active=false archives, which is not deletion but does hide
the project and freeze its work packages. Changing identifier is deliberately not
offered — it breaks every existing link to the project.
Cross-references: get_project to read the current values first; delete_project
to remove a project for good; list_projects(active=false) to find archived ones.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New display name. Omit to leave the name alone. | |
| active | No | false ARCHIVES the project — it disappears from normal listings and everything in it becomes read-only, including its subprojects. true restores it. Omit to leave it alone. Archiving is usually admin-only. | |
| public | No | True publishes the project to every logged-in user, false makes it members-only. Omit to leave the visibility alone. | |
| parent_id | No | Move the project under another one: numeric id or identifier of the new parent. Pass null to detach it and make it top-level. Omit the parameter entirely (the default) to leave the hierarchy untouched. | __unchanged__ |
| description | No | New description in markdown; it REPLACES the existing text, so read the current one with get_project first if you mean to extend it. Pass an empty string to clear it. Omit to leave it alone. | |
| status_code | No | New project status: on_track, at_risk, off_track, not_started, finished or discontinued. Only these codes are accepted. Omit to leave the status alone. | |
| id_or_identifier | Yes | Numeric project id or URL identifier of the project to change; both are accepted and come from list_projects or get_project. | |
| status_explanation | No | Markdown note explaining the status, e.g. why the project is at risk. Replaces the previous explanation; pass an empty string to clear it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Numeric project id; accepted by every project_id parameter. | |
| name | No | Display name. | |
| active | No | False for archived projects (read-only in the UI). | |
| parent | No | Parent project, when this is a subproject. | |
| public | No | True when visible to users without a membership. | |
| created_at | No | ISO 8601 UTC timestamp. | |
| identifier | No | URL slug from /projects/<identifier>; also accepted wherever an id is. | |
| updated_at | No | ISO 8601 UTC timestamp. | |
| description | No | Description as markdown (raw); html is dropped. | |
| status_code | No | Project status code, one of: on_track, at_risk, off_track, not_started, finished, discontinued. A code, never a translated label; null means no status has been set. | |
| workspace_type | No | Workspace kind: 'project', 'program' or 'portfolio'. Pre-17 instances only have 'project'; on 17.x project listings mix all three kinds, so check this before treating a row as a plain project. | |
| status_explanation | No | Free-text explanation of status_code, markdown (raw). |