Decisions | kanman documentation

Decisions are everything kanman needs a human for: plan approvals, policy exceptions, clarification questions, budget stops and failed verifications. Each decision that waits for you comes with kanman’s recommendation and 2 to 4 options. See Decisions for the concept. You answer decisions in the app, in Slack or through the REST API.

Answer a decision

Where	How
App	Decisions (`/<workspace>/decisions`), tabs Pending and Resolved, or the decision page `/<workspace>/decisions/<decision-key>`. Approving options take one click; rejecting, requesting changes, answering, abandoning and declining open a short note first.
Slack	The buttons under the decision message in the team’s channel, or a reply to kanman in the thread, for example “approve” or “reject dec-4h2k”. See Answer decisions from Slack.
Intake	A reply in the team’s intake that names the decision, for example “approve dec-4h2k”.
REST API	`POST /v1/decisions/<decision-key>/resolve` with a token that has the `write` permission. See below.

The first answer wins. Whoever answers second is told that the decision is already resolved. Every answer writes a decision_resolved audit entry with the person and the channel, shown on the decision as “resolved via” the app, Slack, the MCP server or the API.

Kinds

Kind	Raised when
`plan_approval`	The policy requires plan approval for this story.
`policy_exception`	The story needs something the policy does not allow, for example a denied path.
`clarification`	The coding agent asked a question through `request_human_input`.
`budget_stop`	The run reached its budget.
`verification_failed`	Verification failed after the automatic rework attempt.
`gate_failure`	Writing a working acceptance spec for the story failed.
`diff_guard`	The implementation changed the acceptance spec.
`repeated_gate_failure`	A gate failed more often than `gate_failure_budget` allows.
`merge_approval`	A verified change is larger than the policy allows to merge automatically.
`revert_approval`	A kanman merge broke the main branch and kanman proposes a revert.
`main_red_incident`	The main branch is red; merges are held.
`maintenance_proposal`	Maintenance mode found something worth a story.
`strategy_proposal`	kanman proposes a feature based on your repository’s strategy notes.
`scope_change`	Doing the story well would mean changing its scope.

Option actions

Action	Effect
`approve_plan`	The plan is approved; implementation starts.
`request_changes`	The run continues with your note as input.
`allow_once`	The policy exception is granted for this run only.
`reject`	The run ends and the story returns to Backlog with your note.
`raise_budget`	The run budget is raised, by default to double the cap, and the run continues.
`abandon`	The run ends and the story returns to Backlog.
`revert_spec_and_retry`	kanman restores the acceptance spec and starts a new attempt.
`retry`	A new attempt starts, with your note as guidance.
`answer`	Your answer is passed to the coding agent and the run continues.
`merge`	The pull request is merged.
`open_revert`	kanman opens a revert pull request.
`accept_proposal`	The proposal is filed as a story or goes to intake.
`decline_proposal`	The proposal is declined and remembered.

REST API

List decisions

GET /v1/decisions returns the workspace’s decisions, newest first, paginated. Filter with status (pending, resolved, expired, cancelled, superseded), team (team slug) and run (run key).

curl "https://api.kanman.ai/functions/v1/api-gateway/v1/decisions?status=pending" --header "Authorization: Bearer $KANMAN_API_KEY"

Field	Description
`key`, `kind`, `authority`, `title`, `body`	The decision; `body` holds kanman’s reasoning as Markdown.
`status`, `recommendation`	The state and the id of the option kanman recommends.
`options`	`id`, `label`, `action` and `recommended` per option.
`team`, `story`, `runKey`	Where the decision belongs.
`resolution`, `resolvedVia`, `resolvedAt`	The answer (`optionId`, `note`) and its channel, once resolved.
`expiresAt`, `createdAt`	Timestamps.

GET /v1/decisions/{decision-key} returns one decision in the same shape.

Answer a decision through the API

POST /v1/decisions/{decision-key}/resolve needs a token with the write permission. The answer is recorded with the token’s owner as the person who answered and api as the channel, and has the same effect as answering in the app.

curl -X POST https://api.kanman.ai/functions/v1/api-gateway/v1/decisions/dec-4h2k/resolve \
  --header "Authorization: Bearer $KANMAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"optionId": "approve", "note": "Looks good"}'

Body field	Description
`optionId`	Required. The `id` of one of the decision’s options.
`note`	Optional, up to 4,000 characters. Passed on like a note in the app.

The answer is the updated decision plus effects, the steps kanman took. 400 means the option does not exist, 404 that the decision is not in the token’s workspace, 409 that it was already answered (the first answer wins).