Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

update_project_settings

Changes the settings every later module reads, from the sprint length to the council's seats, after the person confirms.

Change a project's settings by project_id: any of sprint_length_days, working_days, timezone, estimation_unit, story_point_scale, default_assignee_rule, auto_transition_on_pr, auto_transition_on_merge, require_dor_for_sprint, require_dod_for_done, guest_can_comment, ai_assist_enabled, telegram_group_chat_id, wip_limits, hidden_columns, business_hours, auto_incident_on_down, council_voices and council_budget_percent. A key left out keeps its value. The change goes through the same action the Settings page runs and project.settings_changed goes out with the keys that moved.

The tool is destructive in the MCP sense: a setting changes how the project behaves rather than what it says, so a Heimdall turn pauses for the person's confirmation and an MCP client asks before sending. A staff token with project:update on the project is needed.

Requires ability

project:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same action as

PATCH/v1/projects/{project}/settings

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires one event

project.settings_changed

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

project_id*string

UUID of the project.

sprint_length_daysintegeroptional

How long a sprint runs, 1 to 60 days.

working_daysinteger[]optional

The working days as ISO weekday numbers, Monday 1 to Sunday 7.

timezonestringoptional

The timezone the project's deadlines are read in, such as Asia/Colombo; null for the workspace default.

estimation_unitstringoptional

What work is sized in.

pointshours
story_point_scalestringoptional

The scale story points come from.

fibonaccilineartshirt
default_assignee_rulestringoptional

Who a new item is handed to by default.

reporterleadnone
auto_transition_on_prbooleanoptional

Whether an opened pull request moves its story into review.

auto_transition_on_mergebooleanoptional

Whether a merged pull request moves its story on.

require_dor_for_sprintbooleanoptional

Whether a story needs its definition of ready ticked before a sprint takes it.

require_dod_for_donebooleanoptional

Whether an item needs its definition of done ticked before it is done.

guest_can_commentbooleanoptional

Whether client guests may comment.

ai_assist_enabledbooleanoptional

Whether Heimdall assists on this project at all.

telegram_group_chat_idstringoptional

The Telegram group the project speaks in; null for none.

wip_limitsobjectoptional

A map of board column code to its work-in-progress limit.

hidden_columnsstring[]optional

The board columns the project hides.

business_hoursobjectoptional

An object with start and end as HH:MM, the hours SLAs count.

auto_incident_on_downbooleanoptional

Whether a production environment found down twice opens an incident.

council_voicesobjectoptional

A map of council moment code to the voice keys that sit on it.

council_budget_percentintegeroptional

The share of the team's monthly AI budget the council may spend here, 1 to 100.

What it returns

{  "data": {    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "sprint_length_days": 7,    "working_days": [1, 2, 3, 4, 5],    "timezone": "Asia/Colombo",    "estimation_unit": "points",    "story_point_scale": "fibonacci",    "default_assignee_rule": "nobody",    "auto_transition_on_pr": true,    "auto_transition_on_merge": true,    "require_dor_for_sprint": false,    "require_dod_for_done": true,    "guest_can_comment": true,    "ai_assist_enabled": true,    "telegram_group_chat_id": null,    "wip_limits": { "in_progress": 4 },    "hidden_columns": [],    "business_hours": { "start": "09:00", "end": "18:00" },    "auto_incident_on_down": true,    "council_voices": {      "intake_scaffold": ["odin", "thor", "loki", "tyr", "frigg", "baldur"]    },    "council_budget_percent": 25  }}

How it fails

VALIDATION_FAILED

a sprint length outside 1 to 60, a weekday outside 1 to 7, an unknown timezone, a unit, scale or rule outside its set, a WIP limit on an unknown column, business hours without both ends, a council voice that does not exist, or a budget share outside 1 to 100.

RESOURCE_NOT_FOUND

unknown project_id, or a project outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry project:update.

TOKEN_MISSING_ABILITY

token lacks project:update.

Related

get_project_settingsthe settings as they stand.update_projectthe project's own record.Project settings APIthe same door over REST.

How is this guide?

Last updated on