openapi: 3.1.0
info:
  title: kanman REST API (story endpoints)
  version: "1"
  description: |
    Start work on a team and read its status. Authenticate with a km_ API token
    (Your settings > API tokens). Every write acts as the token's owner, who must be an
    owner, admin or member of the workspace. Errors have the shape
    {"error": {"code": "...", "message": "..."}}. 120 requests per minute per token.
servers:
  - url: https://api.kanman.ai/functions/v1/api-gateway/v1
security:
  - bearer: []
paths:
  /teams/{team}/stories:
    post:
      summary: Create a story
      description: |
        The story lands in the team's Backlog and kanman picks it up like any new request.
        With "ready": true it is created straight in Ready, which needs the stories:ready scope.
      operationId: createStory
      x-scopes: [stories:create, "stories:ready (only with ready: true)"]
      parameters:
        - $ref: '#/components/parameters/team'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              additionalProperties: false
              properties:
                title: { type: string, minLength: 1, maxLength: 200 }
                description: { type: string, maxLength: 20000 }
                ready: { type: boolean, default: false }
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  key: { type: string, example: SBX-42 }
                  team: { type: string, example: sandbox-team }
                  stage: { type: string, enum: [intake, ready] }
                  kanmanNotified: { type: boolean }
                  url: { type: [string, 'null'], format: uri }
        '400': { $ref: '#/components/responses/error' }
        '401': { $ref: '#/components/responses/error' }
        '403': { $ref: '#/components/responses/error' }
        '404': { $ref: '#/components/responses/error' }
        '429': { $ref: '#/components/responses/error' }
  /stories/{storyKey}:
    get:
      summary: Read a story and its status
      operationId: getStory
      x-scopes: [read]
      parameters:
        - $ref: '#/components/parameters/storyKey'
      responses:
        '200':
          description: The story with its column (role backlog, refining, ready, in_progress, review or done), acceptance criteria and run keys
          content:
            application/json:
              schema: { type: object }
        '404': { $ref: '#/components/responses/error' }
  /stories/{storyKey}/comments:
    post:
      summary: Comment on a story
      operationId: commentOnStory
      x-scopes: [stories:comment]
      parameters:
        - $ref: '#/components/parameters/storyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, minLength: 1, maxLength: 20000 }
                toKanman: { type: boolean, default: true, description: Address the comment to kanman }
      responses:
        '201':
          description: Commented
          content:
            application/json:
              schema:
                type: object
                properties:
                  key: { type: string }
                  comment: { type: string }
                  toKanman: { type: boolean }
                  url: { type: [string, 'null'], format: uri }
        '400': { $ref: '#/components/responses/error' }
        '403': { $ref: '#/components/responses/error' }
        '404': { $ref: '#/components/responses/error' }
  /stories/{storyKey}/start:
    post:
      summary: Start work on a written story
      description: Like "Start now" in the app. A story you stopped goes back to kanman first.
      operationId: startStory
      x-scopes: [stories:start]
      parameters:
        - $ref: '#/components/parameters/storyKey'
      responses:
        '200':
          description: Started or already started
          content:
            application/json:
              schema:
                type: object
                properties:
                  key: { type: string }
                  state: { type: string, enum: [started, already_started] }
                  handedBack: { type: boolean }
                  waitsForSlot: { type: boolean }
        '409':
          description: The story cannot start yet
          content:
            application/json:
              schema:
                type: object
                properties:
                  key: { type: string }
                  state: { type: string, enum: [not_written, needs_plan, needs_yes] }
                  message: { type: string }
                  plan: { type: string }
        '404': { $ref: '#/components/responses/error' }
  /stories/{storyKey}/stop:
    post:
      summary: Stop work on a story
      description: kanman stops working on the story and leaves it to you until you start it again.
      operationId: stopStory
      x-scopes: [stories:start]
      parameters:
        - $ref: '#/components/parameters/storyKey'
      responses:
        '200':
          description: Stopped
          content:
            application/json:
              schema:
                type: object
                properties:
                  key: { type: string }
                  state: { type: string, enum: [stopped] }
                  message: { type: string }
        '409': { $ref: '#/components/responses/error' }
        '404': { $ref: '#/components/responses/error' }
  /runs/{runKey}:
    get:
      summary: Read a run and its status
      operationId: getRun
      x-scopes: [read]
      parameters:
        - name: runKey
          in: path
          required: true
          schema: { type: string, example: run-7f3k }
      responses:
        '200':
          description: The run with its attempts
          content:
            application/json:
              schema: { type: object }
        '404': { $ref: '#/components/responses/error' }
components:
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: A km_ API token
  parameters:
    team:
      name: team
      in: path
      required: true
      schema: { type: string, example: sandbox-team }
    storyKey:
      name: storyKey
      in: path
      required: true
      schema: { type: string, example: SBX-42 }
  responses:
    error:
      description: An error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code: { type: string, enum: [invalid_request, unauthorized, forbidden, not_found, method_not_allowed, conflict, rate_limited, internal_error] }
                  message: { type: string }
