Config Lists API

All endpoints require authentication and config-lists tool permissions.

List Config Lists

GET /api/config-lists

Permission: config-lists / view

Returns all config lists with their items pre-loaded.

Query parameters:

Param	Type	Description
key	string	Filter by list key (e.g. task_status, deal_stage, task_priority)

Response: { lists }

Each list includes id, key, name, description, is_system, and a nested items array ordered by position then label.

Get List Items

GET /api/config-lists/:key/items

Permission: config-lists / view

Returns items for a specific list by its key.

Path parameters:

Param	Type	Description
key	string	List key

Response: { items }

Each item includes id, list_id, label, value, color, icon, is_default, is_system, and position.

Create List Item

POST /api/config-lists/:key/items

Permission: config-lists / manage

Path parameters:

Param	Type	Description
key	string	List key

Request body:

Field	Type	Description
label	string	Display label (required)
value	string	Internal value (required)
color	string	Hex colour for display
icon	string	Icon name
is_default	boolean	Set as the default item for this list
position	number	Sort order (default: 99)
stage_type	string	Stage type for pipeline lists (e.g. not_started, in_progress, done)
probability	number	Win probability for deal stages
email_template_id	string	Email template to trigger on transition
email_trigger_active	boolean	Whether the email trigger is active

Response: { item } (201)

Update List Item

PUT /api/config-lists/:key/items/:itemId

Permission: config-lists / manage

System items have restricted editing (the value field cannot be changed on system items).

Path parameters:

Param	Type	Description
key	string	List key
itemId	string	Item ID

Request body: Any of label, value, color, icon, is_default, position, stage_type, probability, email_template_id, email_trigger_active.

When setting is_default: true, any existing default item in the same list is cleared first.

Response: { item }

Reorder List Items

PUT /api/config-lists/:key/reorder

Permission: config-lists / manage

Bulk-reorders items by setting their position based on array index.

Path parameters:

Param	Type	Description
key	string	List key

Request body:

Field	Type	Description
item_ids	string[]	Ordered array of item IDs

Response: { ok: true }

Delete List Item

DELETE /api/config-lists/:key/items/:itemId

Permission: config-lists / manage

System items cannot be deleted.

Path parameters:

Param	Type	Description
key	string	List key
itemId	string	Item ID

Response: { ok: true }