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
- Open your workspace; it opens on the conversation with kanman. Choose the team on the chip of the message box (or press
Nwhile you look at the team). - 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