Create project
create_projectCreate a new project or subproject in OpenProject, pre-validating the form to catch invalid identifiers, parent, or status as named violations before commit. Returns the created project's id, identifier, and metadata.
Instructions
Create a project, validated through OpenProject's own form endpoint first.
Use it for a new workspace or, with parent_id, for a subproject of an existing
one. The call runs POST /projects/form before committing, so a taken identifier,
an unusable parent or a bad status comes back as violations naming the attribute
instead of an opaque failure — and the identifier OpenProject derives from the name
is used verbatim on the commit.
Returns the created project: {id, identifier, name, active, public, parent, status_code, description, status_explanation, created_at, updated_at}. Keep the
id — every other tool's project_id accepts it, as does the identifier.
Pitfalls: creating projects usually requires the 'create project' permission or
admin rights, so a 403 here is about the account, not the payload. The new project
starts with the instance's default modules and types enabled — check
get_project_metadata(project_id=...) before creating work packages in it.
Members are not copied from the parent; add them with create_membership.
Cross-references: list_projects finds the parent id; update_project changes
any of these fields afterwards; get_project_metadata lists the types, versions
and categories valid inside the result.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Display name of the new project, e.g. 'Apollo migration'. Names need not be unique on the instance; the identifier is what must be. | |
| public | No | True makes the project visible to every logged-in user without a membership. Omit to take the instance default (normally private). | |
| parent_id | No | Numeric id or identifier of the parent project, to create a subproject. Ids come from list_projects. Omit for a top-level project. Creating a subproject needs the 'add subprojects' permission on the parent. | |
| identifier | No | URL slug for /projects/<identifier>: lowercase letters, digits, '-' and '_' only, unique across the whole instance. Omit it and OpenProject derives one from the name — the derived value is in the result. A slug that is already taken comes back as a validation violation, not a surprise rename. | |
| description | No | Project description in markdown. Omit to leave it empty. | |
| status_code | No | Initial project status: on_track, at_risk, off_track, not_started, finished or discontinued. These codes are the only accepted values — a free-text status is rejected rather than silently dropped. Omit for no status. |
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). |