Skip to content
GitmoapAPIBeta
Planissues
POST/groups/{group_id}/iterations/{iteration_id}/roll-over

Roll an iteration's unfinished work over

roll_over_iteration
  • iteration:manage
    A token needs the iteration:manage scope: Define and remove iterations and their cadences, and roll an iteration's unfinished work overGranted by write_api, write_repository.Every operation this scope unlocks
  • Audited · mutation

    x-gitmoap-audit: {"kind":"audited","arg":"mutation"}

Moves every work item still open in the iteration to another iteration of the same group — by default the next one of its cadence — and records the move on each item's activity. Completed and cancelled work stays in the iteration that did it, so the iteration keeps its record of what it finished. Nothing rolls over by itself when an iteration ends; this is the explicit step. The destination must not have ended. Maintainers and above may roll work over.

Parameters

Path
  • group_idGroupId (string · uuid)Group ID
  • iteration_idIterationId (string · uuid)Iteration ID — the one the work comes from

Request body

application/json
  • to_iteration_idIterationId (string · uuid) or nulloptionalThe iteration to move the open work items to, in the same group. Defaults to the next iteration of the same cadence; an iteration created by hand has no next one, so for it this is required.
Request body exampleSynthesized example
{}

Responses

200Where the work went, and how much of itapplication/json
  • from_iteration_idIterationId (string · uuid)The iteration the work came from. Its completed and cancelled work stays in it.
  • movedinteger · int320–∞How many open work items moved.
  • toIterationThe iteration the open work went to.
    • The Iteration schema
    • created_atstringWhen it was created, ISO 8601.
    • due_dateCalendarDate (string)Its last day, included.
    • group_idGroupId (string · uuid)The group it belongs to.
    • iteration_idIterationId (string · uuid)The iteration's identifier.
    • start_dateCalendarDate (string)Its first day.
    • stateIterationStateupcomingcurrentclosedWhether it is upcoming, current or closed today, read from its dates — never stored.
    • titleIterationTitle (string)Its title.
    • updated_atstringWhen it last changed, ISO 8601.
    • cadence_idCadenceId (string · uuid) or nulloptionalThe cadence that generated it. Absent for an iteration created by hand, and for one whose cadence was deleted.
    • descriptionstring or nulloptionalWhat it is for, in Markdown. Absent when it has none.
    • sequenceinteger · int32 or nulloptional0–∞Its position in the cadence that generated it, counted from 1. Absent for an iteration created by hand.
200 exampleSynthesized example
{
"from_iteration_id": "eab1b26b-2faf-4394-ad95-b2c09418bee0",
"moved": 88,
"to": {
"created_at": "2026-10-15T08:37:19Z",
"due_date": "due-date-39d8",
"group_id": "4c1d8e2f-6a3b-4f90-b7c5-1e2d3c4b5a69",
"iteration_id": "69122588-16f8-462f-980d-da94249733e5",
"start_date": "start-date-9d97",
"state": "upcoming",
"title": "Pin a page's payload to the build that rendered it",
"updated_at": "2026-10-09T20:41:45Z",
"cadence_id": "70e81f51-b5c9-4fc7-9c5d-8689234def5a",
"description": "Renders each region as density contours of its operations.",
"sequence": 23
}
}
400An iteration of no cadence with no destination named, or the same iteration twiceapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
400 exampleSynthesized example
{
"error": {
"code": "code-73dd",
"message": "Stream pipeline status into the run header"
}
}
401Unauthenticated — no credential, or an invalid oneapplication/json
Error codes
  • UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
401 exampleSynthesized example
{
"error": {
"code": "code-6824",
"message": "Stream pipeline status into the run header"
}
}
403Forbidden — the caller's access level or token scope is insufficientapplication/json
Error codes
  • FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
  • INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
403 exampleSynthesized example
{
"error": {
"code": "code-7fe3",
"message": "Draw the region map from operation density"
}
}
404Either iteration is not found in this groupapplication/json
Error codes
  • NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
404 exampleSynthesized example
{
"error": {
"code": "code-a911",
"message": "Draw the region map from operation density"
}
}
409The cadence's next iteration has not been created, or the destination has endedapplication/json
Error codes
  • CONFLICTThe request conflicts with the resource's current state; reason says how
  • LEGAL_ACCEPTANCE_REQUIREDAccept the current Terms of Service before changing anything; reading stays open
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
409 exampleSynthesized example
{
"error": {
"code": "code-b13b",
"message": "Pin a page's payload to the build that rendered it"
}
}

CLI

gitmoap issues roll-over-iteration

  • --group-ididGroup ID (id or group path)
  • --iteration-ididIteration ID — the one the work comes from
  • --to-iteration-idstringoptional

Used in these guides