Skip to main content

Create a MULTI-PROJECT cycle (PT-938) — the third scope arm

POST 
/api/cycles

Create a MULTI-PROJECT cycle (PT-938) — the third scope arm. This is the ONE cycle-create route whose scope owner travels in the BODY rather than the URL, and that is the reason the other arms take it from the URL rather than an exception to it: they address an owner that already exists, while this one's owner is DERIVED from projectIds and may not exist yet, so there is no id to put in a path. The server resolves it: the project set covering exactly that combination is reused if one exists, and created otherwise, so picking the same projects again yields Sprint 2 of that combination rather than a fresh owner at sequence 1 — which is what keeps one-active-per-scope, recurring rollover (PT-800) and auto-close (PT-844) meaningful on this arm. Two callers picking the same projects concurrently converge on ONE owner. projectIds needs at least TWO distinct projects: one project is an ordinary project-scoped cycle, created at /api/projects/{id}/cycles — no single-member set is ever made. Every project must belong to the active organisation. Requires tasks.create in that organisation; the cycle is born planned and is activated / completed / edited through the /api/cycle-sets/{id}/cycles/{cycleId} routes below.

PT-1104: the same route creates an ORGANISATION cycle when the body carries organisationScope: true instead of projectIds — owned by the active organisation itself and admitting every task of it; edited through /api/organisation-cycles/{cycleId}. Every create is subject to the organisation’s cycle mode (see /api/cycle-settings): a single-mode organisation accepts only organisation cycles and a multi-mode one refuses them, and no dated cycle may share a UTC day with another planned or active cycle of the same track. An organisation cycle must carry a start and an end date.

Request​

Responses​

Successful response