ConnectCloud Developers

Close an iteration (tenant:forge:write and, as a member, at least developer)

POST /api/forge/v1/projects/{key}/iterations/{id}/close

Module: Forge · operationId: closeForgeIteration · Tag: Iterations · Auth: access token (Authorization: Bearer <accessToken>)

Same permission as creating. Only the active iteration closes (409 iteration_not_active). The state of every item in it is snapshotted first; then the open items (status category not done or cancelled) move to the planned iteration nextIterationId (carryOver next; 400 nextIterationId when it is missing or not a planned iteration of the project) or to the backlog (carryOver backlog). Each move is an item change recorded as updated with the change iteration; everything happens in one transaction. Done and cancelled items stay in the closed iteration. Writes forge.iteration.closed and forge.item.updated per moved item.

Parameters

Name In Type Required Description
key path string yes Project key (e.g. APP)
id path string (uuid) yes

Request body

application/json (required)

  • carryOver (string, required): Where the open items go (one of next, backlog)
  • nextIterationId (string (uuid)): Required with next: a planned iteration of the project; not allowed with backlog

Example:

{
  "carryOver": "next",
  "nextIterationId": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d03"
}

Responses

  • 200 Closed (application/json)
  • 400 Error (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)
  • 409 Error (application/json)

Fields of the 200 answer:

  • closedAt (string (date-time), nullable, required): When it was closed; null until then
  • createdAt (string (date-time), required): When it was created
  • endsOn (string (date), required): Last day
  • goal (string, required): Goal of the iteration
  • id (string (uuid), required): Iteration id
  • name (string, required): Name
  • position (integer, required): Order of the iterations
  • startedAt (string (date-time), nullable, required): When it was started; null while planned
  • startsOn (string (date), required): First day
  • state (string, required): planned, active (at most one per project) or closed (one of planned, active, closed)
  • updatedAt (string (date-time), required): Last change
  • version (integer, required): Optimistic-locking version; send it with PATCH
  • progress (IterationProgress, required): Planned and active iterations count the items in them now; a closed iteration counts its snapshot (every item as it stood at the close, carried-over ones included).

Example 200 answer:

{
  "closedAt": "2026-11-25T08:30:00Z",
  "createdAt": "2026-10-28T11:00:00Z",
  "endsOn": "2026-11-24",
  "goal": "Kunden sehen ihre Tickets mit Filtern und laden lange Listen nach.",
  "id": "f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d02",
  "name": "Iteration 2 – Ticketübersicht",
  "position": 1,
  "progress": {
    "byCategory": {
      "active": 1,
      "cancelled": 0,
      "done": 5,
      "on_hold": 0,
      "todo": 1,
      "triage": 0
    },
    "committed": 16,
    "estimate": {
      "done": 12,
      "total": 19
    },
    "total": 7
  },
  "startedAt": "2026-11-04T09:30:00Z",
  "startsOn": "2026-11-04",
  "state": "closed",
  "updatedAt": "2026-11-25T08:30:00Z",
  "version": 4
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/iterations/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/close' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"carryOver":"next","nextIterationId":"f1b2c3d4-e5f6-4a7b-9c34-1f2a3b4c5d03"}'

View as Markdown · Interactive reference · OpenAPI