OpenProject API v3 endpoint map

Base: <server>/api/v3. Auth: HTTP Basic, username apikey, password = API token (the CLI handles this). Responses are HAL+JSON: _type, _links, _embedded. Collections carry total, count, pageSize, and _embedded.elements.

Endpoints the op.py CLI wraps directly are marked ✅. Everything else is reachable via op.py raw <METHOD> <path> [--data '{...}'].

Work packages

✅ GET /work_packages — list/filter (also /projects/{id}/work_packages)
✅ GET /work_packages/{id} — single
✅ POST /work_packages — create
✅ PATCH /work_packages/{id} — update (needs lockVersion; CLI auto-fetches)
✅ DELETE /work_packages/{id} — delete
✅ POST /work_packages/{id}/activities — add comment
GET /work_packages/{id}/activities — comment/change history
GET /work_packages/{id}/relations · POST /relations — links between WPs
GET /work_packages/{id}/watchers · POST .../watchers
GET /work_packages/form · POST /work_packages/{id}/form — field schema/validation
GET /work_packages/schemas — allowed values per project+type

Projects

✅ GET /projects — list/filter (name_and_identifier filter)
✅ GET /projects/{id} — single (id or identifier)
POST /projects · PATCH /projects/{id} · DELETE /projects/{id}
✅ GET /projects/{id}/types — types enabled in a project
GET /projects/{id}/versions — versions/milestones
GET /projects/{id}/categories
GET /projects/{id}/memberships

People & metadata

✅ GET /users/me — current user (ping/me)
✅ GET /users — list/filter
GET /groups · GET /roles
✅ GET /types · GET /statuses · GET /priorities
GET /time_entries/activities — activity types for time logging

Time tracking

✅ POST /time_entries — log time (hours is ISO-8601 duration, e.g. PT1H30M; CLI accepts a plain number of hours and converts)
GET /time_entries — list/filter
PATCH /time_entries/{id} · DELETE /time_entries/{id}

Other useful resources

GET /queries · GET /queries/{id} — saved views (filters+columns+sort)
GET /versions/{id} — milestone detail
GET /attachments/{id} · POST /work_packages/{id}/attachments — files
GET /notifications — in-app notifications
GET /memberships — project membership management

Notes

lockVersion / optimistic locking: any PATCH to a work package must include the lockVersion you got from the last GET. If it's stale, the API returns 409/422 — re-fetch and retry. The CLI does this automatically for wp update/wp close.
Durations: time values use ISO-8601 (PT1H, PT30M, P1DT2H). The CLI's time log --hours 1.5 emits PT1.5H.
Markdown fields: description and comment take {"format":"markdown","raw":"..."}.
Form endpoints (POST .../form) validate a payload and return allowed values without persisting — handy when unsure which statuses/types are valid for a project.

3.0 KiB Raw Permalink Blame History