Iterations

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

Parameter	Required	Description
`projectId`	Yes	The project to query
`status`	No	Filter: `active` or `done`
`current`	No	Set 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

Field	Type	Description
`name`	string	Iteration name (unique within project)
`status`	string	`active` or `done`
`system`	boolean	System iterations (e.g. “Later”) can’t be deleted
`sortOrder`	number	Display order
`gitTags`	string[]	Associated git tags (optional)
`completedAt`	number	Timestamp 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"]
  }'

Overview

Endpoints

List Iterations

Parameters

Get all iterations

Get the current iteration

Iteration fields

Create an Iteration

Update an Iteration

Delete an Iteration

Reorder Iterations

​List Iterations

​Parameters

​Get all iterations

​Get the current iteration

​Iteration fields

​Create an Iteration

​Update an Iteration

​Delete an Iteration

​Reorder Iterations

List Iterations

Parameters

Get all iterations

Get the current iteration

Iteration fields

Create an Iteration

Update an Iteration

Delete an Iteration

Reorder Iterations