# 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.