Stories and intake

Where you submit requirements, review draft stories and edit stories, and how your tools read stories through the REST API.

A story is a tracker issue that kanman mirrors, with acceptance criteria 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, create them and start work through the REST API.

Submit a requirement

  1. Open your workspace; it opens on the conversation with kanman. Choose the team on the chip of the message box (or press N while you look at the team).
  2. Describe what you need and press Enter.

kanman sorts every message first. A work request becomes draft stories; a vague one gets up to three questions back, which you answer in the conversation. 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 drafts arrive as a card in the conversation, where you Approve or Reject each one. Open review opens all drafts of a request at /<workspace>/teams/<team>/intake/<intake-slug>, where you can also edit the text and acceptance criteria. Only stories that are ready (readiness score 100 and no blocking open questions) can be approved; workspace owners and admins can also approve a story that only open questions hold back (Approve with open questions, recorded as story_approved_open). 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 and its runs. Members edit acceptance criteria there; kanman recomputes the readiness score with every change.

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).

Start work

A token can start work on a team, as the person who created it. Each call needs its own permission; Write includes the first three. The token’s owner must be an owner, admin or member of the workspace: a viewer’s token is answered with 403.

Method and path What it does Permission
POST /v1/teams/{team}/stories Create a story. It lands in the Backlog and kanman picks it up like any new request. stories:create
POST /v1/teams/{team}/stories with "ready": true Create the story straight in Ready, without kanman’s intake. stories:create and stories:ready
POST /v1/stories/{story-key}/comments Comment on a story as you. The comment is addressed to kanman unless you send "toKanman": false. stories:comment
POST /v1/stories/{story-key}/start Start a written story, like Start now in the app. A story you stopped goes back to kanman first. stories:start
POST /v1/stories/{story-key}/stop kanman stops working on the story and leaves it to you until you start it again. stories:start
curl https://api.kanman.ai/functions/v1/api-gateway/v1/teams/sandbox-team/stories \
  --header "Authorization: Bearer $KANMAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"title":"Export invoices as CSV","description":"Finance needs a monthly CSV of all invoices."}'
{ "key": "SBX-42", "team": "sandbox-team", "stage": "intake", "kanmanNotified": true, "url": "https://app.kanman.ai/acme/teams/sandbox-team/stories/SBX-42" }

title is required (at most 200 characters); description is optional (at most 20,000). stage is intake or ready.

curl https://api.kanman.ai/functions/v1/api-gateway/v1/stories/SBX-42/comments \
  --header "Authorization: Bearer $KANMAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"text":"The customer confirmed the expected columns: date, number, amount."}'

curl -X POST https://api.kanman.ai/functions/v1/api-gateway/v1/stories/SBX-42/start \
  --header "Authorization: Bearer $KANMAN_API_KEY"

start answers 200 with state started (and waitsForSlot when every run slot is taken) or already_started, and 409 with not_written, needs_plan or needs_yes and a message when the story cannot start yet. stop answers 409 when a person already holds the story.

Read the status of a story with GET /v1/stories/{story-key} and of a run with GET /v1/runs/{run-key}. The OpenAPI description covers these endpoints. To let another system report events to a team without a token, use a team webhook.

Last updated: January 1, 0001

Open kanman