Skip to main content
Iterations are thematic delivery slices, bundles of work that ship together. They are not sprints (no fixed timebox) and not releases (no deployment coupling).

​
List Iterations

GET /api/v1/iterations?projectId={projectId}

​
Parameters

ParameterRequiredDescription
projectIdYesThe project to query
statusNoFilter: active or done
currentNoSet to true to get only the current iteration

​
Get all iterations

curl -s "https://productbrain.com/api/v1/iterations?projectId=my-project" \
  -H "Authorization: Bearer pb_..."

{
  "iterations": [
    {
      "name": "MVP",
      "status": "active",
      "system": false,
      "sortOrder": 1
    },
    {
      "name": "Later",
      "status": "active",
      "system": true,
      "sortOrder": 99
    }
  ]
}

​
Get the current iteration

The current iteration is the first active, non-system iteration by sort order. Use this when you need to know what’s being worked on now. 
curl -s "https://productbrain.com/api/v1/iterations?projectId=my-project&current=true" \
  -H "Authorization: Bearer pb_..."

{
  "iteration": {
    "name": "MVP",
    "status": "active",
    "system": false,
    "sortOrder": 1
  }
}

​
Iteration fields

FieldTypeDescription
namestringIteration name (unique within project)
statusstringactive or done
systembooleanSystem iterations (e.g. “Later”) can’t be deleted
sortOrdernumberDisplay order
gitTagsstring[]Associated git tags (optional)
completedAtnumberTimestamp when marked done (auto-set)

​
Create an Iteration

curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "addIteration",
    "projectId": "my-project",
    "iteration": { "name": "Phase 2" }
  }'

​
Update an Iteration

PATCH semantics. Use this to rename, mark done, or add git tags. 
curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "updateIteration",
    "projectId": "my-project",
    "iterationName": "MVP",
    "data": { "status": "done" }
  }'
Marking an iteration as done automatically sets completedAt. Done iterations are hidden from the UI dropdown and matrix view.

​
Delete an Iteration

System iterations (e.g. “Later”) cannot be deleted. 
curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "deleteIteration",
    "projectId": "my-project",
    "iterationName": "Phase 2"
  }'

​
Reorder Iterations

Pass the full ordered list of iteration names. 
curl -X POST "https://productbrain.com/api/v1/mutate" \
  -H "Authorization: Bearer pb_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reorderIterations",
    "projectId": "my-project",
    "order": ["MVP", "Phase 2", "Phase 3", "Later"]
  }'