Stories and intake | kanman documentation

A story is a tracker issue that kanman mirrors, with acceptance criteria, a Demonstrate block and a readiness score. Your tracker stays the source of truth for title and description. See Stories and acceptance criteria. You submit requirements and work with stories in the app and in Slack.

Your tools read stories through the REST API. Requirements are submitted in the app or in Slack.

Submit a requirement

Open your team and the Intake tab (/<workspace>/teams/<team>/intake), or click New intake.
Describe what you need in Requirement or question and click Send (or press Ctrl+Enter).

kanman sorts every message first. A work request becomes draft stories; a vague one gets up to three questions back, which you answer and send with Draft again. Status questions are answered right there, and short operational requests (“pause the team”, “cancel run-7f3k”) are carried out if you may do them.

You can also mention kanman in a Slack thread of a connected channel; the thread becomes an intake request for that channel’s team. See Answer decisions from Slack.

Review draft stories

The draft stories of a request are at /<workspace>/teams/<team>/intake/<intake-slug>. For each draft you can edit the text and acceptance criteria, Approve or Reject it. Only stories that are ready (readiness score 100, including a Demonstrate step) can be approved. Write N stories to tracker creates the approved ones as issues in your tracker in one go and records story_written in the audit log.

How to write requirements that reach Ready is described in Write requirements kanman can finish.

Read and edit a story

Every story has a page at /<workspace>/teams/<team>/stories/<story-key> with its acceptance criteria, Demonstrate block, the state of its acceptance spec and its runs. Members edit acceptance criteria there; kanman recomputes the readiness score with every change.

The MCP tool get_story returns the same story, with its acceptance criteria, Demonstrate block and test plan, to a coding agent on your machine.

Story keys

Each story has a key made of the team’s key prefix and a number, for example SBX-12. It appears on the board, on the story page and in run and decision titles. The key of the issue in your tracker (for example #12 on GitHub or SBXDE-12 in Jira) can differ from it.

REST API

List a team’s stories

GET /v1/teams/{team}/stories returns the team’s stories, newest first, paginated. Draft stories of an intake request that nobody approved yet are left out; add drafts=true to include them.

curl "https://api.kanman.ai/functions/v1/api-gateway/v1/teams/sandbox-team/stories?limit=50" --header "Authorization: Bearer $KANMAN_API_KEY"

Field	Description
`id`, `key`, `title`, `team`	The story; `team` is the team slug.
`column`	`id`, `name` and `role` (`backlog`, `refining`, `ready`, `in_progress`, `review`, `done`) of the column the story is in.
`draft`	`true` for a draft story that was not approved yet.
`readinessScore`, `size`, `complexity`, `classOfService`	Readiness and sizing.
`tracker`	`platform`, `key` and `url` of the issue in your tracker, or `null`.
`createdAt`, `updatedAt`	Timestamps.

Read a story

GET /v1/stories/{story-key} returns one story, for example SBX-12, with description, acceptanceCriteria and runKeys (the runs of the story, newest first).