Roadmaps API

All endpoints require authentication and roadmaps tool permissions.

List Roadmaps

GET /api/roadmaps

Permission: roadmaps / view

Query parameters:

Param	Type	Description
`project_id`	string	Filter by project ID

Response: { roadmaps }

Each roadmap includes an item_count of linked items.

Get Roadmap

GET /api/roadmaps/:id

Permission: roadmaps / view

Returns a roadmap with all its items and tasks linked to those items.

Path parameters:

Param	Type	Description
`id`	string	Roadmap ID

Response: { roadmap, items, tasks }

Items include goal_title from the linked project goal. Tasks include status_label and status_color.

Create Roadmap

POST /api/roadmaps

Permission: roadmaps / update

Request body:

Field	Type	Description
`name`	string	Roadmap name (required)
`description`	string	Description
`project_id`	string	Linked project ID
`start_date`	string	Start date (YYYY-MM-DD)
`end_date`	string	End date (YYYY-MM-DD)

Response: { roadmap } (201)

Update Roadmap

PUT /api/roadmaps/:id

Permission: roadmaps / update

Path parameters:

Param	Type	Description
`id`	string	Roadmap ID

Request body: Any of name, description, project_id, start_date, end_date.

Response: { roadmap }

Delete Roadmap

DELETE /api/roadmaps/:id

Permission: roadmaps / manage

Path parameters:

Param	Type	Description
`id`	string	Roadmap ID

Response: { ok: true }

Roadmap Items

Create Item

POST /api/roadmaps/:id/items

Permission: roadmaps / update

Path parameters:

Param	Type	Description
`id`	string	Roadmap ID

Request body:

Field	Type	Description
`title`	string	Item title (required)
`description`	string	Description
`goal_id`	string	Linked project goal ID
`area`	string	Swim lane / area label
`start_date`	string	Start date (YYYY-MM-DD)
`end_date`	string	End date (YYYY-MM-DD)
`color`	string	Display colour
`position`	number	Sort order (default: 0)

Response: { item } (201)

Update Item

PUT /api/roadmaps/:id/items/:itemId

Permission: roadmaps / update

Path parameters:

Param	Type	Description
`id`	string	Roadmap ID
`itemId`	string	Item ID

Request body: Any of title, description, goal_id, area, start_date, end_date, color, position.

Response: { item }

Delete Item

DELETE /api/roadmaps/:id/items/:itemId

Permission: roadmaps / update

Path parameters:

Param	Type	Description
`id`	string	Roadmap ID
`itemId`	string	Item ID

Response: { ok: true }