> ## Documentation Index
> Fetch the complete documentation index at: https://sleekplan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Decide on a work item

> A person's decision. Each type needs its own fields:

| `type` | Needs | When | Then |
|---|---|---|---|
| `start` | `stage`; `goal` optional | `needs_decision`, `ready` or `held_back`, and no active run | `ready` at that stage |
| `approve` | | a spec or plan to review | the next stage is `ready` |
| `request_changes` | `text` | as above | the same stage is `ready` again |
| `answer` | `text` | a question is open | back to the waiting run, else `ready` |
| `release` | | a run is active | the run ends, `ready` |
| `complete` | | open or `held_back` | `completed` |
| `close` | | open or `held_back` | `closed` |
| `hold_back` | `until` optional | `needs_decision` or `ready` | `held_back` |
| `reopen` | | `completed`, `closed` or `held_back` | `needs_decision` |

`text` is optional for every other type and is shown with the entry.

A decision that changes nothing, such as `start` with the stage and goal the item already has, writes no entry: `activity` is `null`.



## OpenAPI

````yaml /docs/api/openapi-v2.yaml post /work-items/{number}/decisions
openapi: 3.1.0
info:
  title: Sleekplan API v2
  version: '2.0'
  description: >-
    The `/v2` namespace sits alongside the existing [`/v1`
    API](/docs/api/overview) — it is not a replacement. The same API key
    authenticates both.


    `/v2` accepts **Bearer tokens only**, and carries no workspace ID in the URL
    because the key identifies the workspace. Changes are additive: fields and
    endpoints are added, never removed or renamed.


    See [API v2](/docs/api/v2) for authentication, the error keys, and the rate
    limit.
servers:
  - url: https://api.sleekplan.com/v2
    description: API Version 2
security:
  - BearerAuth: []
tags:
  - name: Group
    description: B2B groups — companies, accounts or teams — and their members.
  - name: Document
    description: >-
      The thinking behind your feedback — a plan, a spec, research, or the
      record of a decision.
  - name: Work item
    description: >-
      What gets worked on next: a brief, evidence and linked posts, moving
      through spec, plan and build.
paths:
  /work-items/{number}/decisions:
    parameters:
      - name: number
        in: path
        required: true
        schema:
          type: integer
    post:
      tags:
        - Work item
      summary: Decide on a work item
      description: >-
        A person's decision. Each type needs its own fields:


        | `type` | Needs | When | Then |

        |---|---|---|---|

        | `start` | `stage`; `goal` optional | `needs_decision`, `ready` or
        `held_back`, and no active run | `ready` at that stage |

        | `approve` | | a spec or plan to review | the next stage is `ready` |

        | `request_changes` | `text` | as above | the same stage is `ready`
        again |

        | `answer` | `text` | a question is open | back to the waiting run, else
        `ready` |

        | `release` | | a run is active | the run ends, `ready` |

        | `complete` | | open or `held_back` | `completed` |

        | `close` | | open or `held_back` | `closed` |

        | `hold_back` | `until` optional | `needs_decision` or `ready` |
        `held_back` |

        | `reopen` | | `completed`, `closed` or `held_back` | `needs_decision` |


        `text` is optional for every other type and is shown with the entry.


        A decision that changes nothing, such as `start` with the stage and goal
        the item already has, writes no entry: `activity` is `null`.
      operationId: v2-decide-work-item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - start
                    - approve
                    - request_changes
                    - answer
                    - release
                    - complete
                    - close
                    - hold_back
                    - reopen
                stage:
                  type: string
                  enum:
                    - spec
                    - plan
                    - build
                goal:
                  type: string
                  enum:
                    - spec
                    - plan
                    - build
                  description: >-
                    How far to go without a person: the work item moves on by
                    itself up to this stage. Not before `stage`; defaults to it.
                text:
                  type: string
                  maxLength: 10000
                  description: Markdown.
                until:
                  type: string
                  format: date
                  example: '2026-12-01'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItemActivityEnvelope'
        '400':
          description: >-
            A field is malformed (`validation_error`), or the goal comes before
            the stage (`invalid_argument`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            `invalid_transition`: the status does not allow this decision. The
            message names what is allowed now.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    WorkItemActivityEnvelope:
      type: object
      description: >-
        The entry the call wrote, or the first one for a repeated report, and
        the work item as it is now.
      properties:
        status:
          type: string
        data:
          type: object
          properties:
            activity:
              oneOf:
                - $ref: '#/components/schemas/WorkItemActivity'
                - type: 'null'
              description: >-
                `null` only for a decision that changed nothing: it writes no
                entry.
            work_item:
              $ref: '#/components/schemas/WorkItem'
    Error:
      type: object
      properties:
        status:
          type: string
          example: error
        data:
          type: object
          properties:
            key:
              type: string
            message:
              type: string
    WorkItemActivity:
      type: object
      description: >-
        One entry of the log: a report, a decision, or a change made in the
        dashboard or through this API.
      properties:
        activity_id:
          type: integer
        type:
          type: string
          example: plan_ready
        kind:
          type: string
          enum:
            - report
            - decision
            - system
        run_id:
          type:
            - integer
            - 'null'
        channel:
          type: string
          enum:
            - app
            - api
            - mcp
            - system
        agent:
          type:
            - string
            - 'null'
        text:
          type:
            - string
            - 'null'
          description: Markdown.
        data:
          type: object
          description: What the entry records. Keys appear only where they apply.
          properties:
            from_status:
              type: string
            to_status:
              type: string
            stage:
              type: string
            goal:
              type: string
            reason:
              type: string
              description: >-
                `goal` on an approval the work item made by itself because the
                goal lay further.
            url:
              type: string
            repository:
              type: string
            pr_number:
              type: integer
            branch:
              type: string
            document_id:
              type: integer
              description: >-
                The spec or plan a delivery saved or linked, or the document an
                `evidence_added` or `evidence_removed` entry added or removed.
                That entry's `text` is the document's title.
            fields:
              type: array
              items:
                type: string
              example:
                - title
                - priority
              description: >-
                What an update changed, by field name: any of `title`, `brief`,
                `priority`, `component`, `owner_id` and `member_ids`. The last
                two say the owner or the members changed, never who they are.
                Ignore a name you do not know: the list may grow.
            feedback_ids:
              type: array
              items:
                type: integer
            until:
              type: string
              format: date
            evidence_id:
              type: integer
        created:
          type: string
    WorkItem:
      type: object
      description: >-
        The published shape of a work item. Fields are added over time and never
        removed: ignore any you do not recognise.
      properties:
        number:
          type: integer
          description: Addresses the work item in every call. Unique per workspace.
          example: 42
        key:
          type: string
          example: WI-42
        title:
          type: string
          example: SAML group mapping
        brief:
          type:
            - string
            - 'null'
          description: Markdown.
        priority:
          type: integer
          minimum: 0
          maximum: 4
        component:
          type:
            - string
            - 'null'
          description: >-
            A component key. A component the workspace deleted since reads as
            `null`.
        status:
          type: string
          enum:
            - needs_decision
            - ready
            - in_progress
            - in_review
            - completed
            - held_back
            - closed
        status_reason:
          type:
            - string
            - 'null'
          enum:
            - new
            - spec_ready
            - plan_ready
            - question
            - failed
            - pr_closed
            - reopened
            - null
          description: Why a person is needed. Set only with `needs_decision`.
        stage:
          type:
            - string
            - 'null'
          enum:
            - spec
            - plan
            - build
            - null
          description: '`null` until the work is started.'
        goal:
          type:
            - string
            - 'null'
          enum:
            - spec
            - plan
            - build
            - null
          description: How far the work item moves on without a person.
        held_until:
          type:
            - string
            - 'null'
          format: date
        source:
          type: string
          enum:
            - app
            - api
            - mcp
          description: >-
            Where it was created: the dashboard, this API, or an agent through
            the Sleekplan MCP server.
        created:
          type: string
          example: '2026-10-29 12:00:00'
        updated:
          type: string
          example: '2026-10-29 12:05:31'
        closed:
          type:
            - string
            - 'null'
          description: When it was completed or closed.
        active_run:
          oneOf:
            - $ref: '#/components/schemas/WorkItemRun'
            - type: 'null'
          description: The run working on it now, or `null`.
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/WorkItemPost'
          description: The linked posts, most voted first.
        demand:
          $ref: '#/components/schemas/WorkItemDemand'
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/WorkItemEvidence'
        documents:
          type: array
          items:
            $ref: '#/components/schemas/WorkItemDocument'
        pull_requests:
          type: array
          items:
            $ref: '#/components/schemas/WorkItemPullRequest'
    WorkItemRun:
      type: object
      description: One claim of a stage. Only one run is active per work item.
      properties:
        run_id:
          type: integer
        stage:
          type: string
          enum:
            - spec
            - plan
            - build
        state:
          type: string
          enum:
            - active
            - done
            - failed
            - released
            - abandoned
        agent:
          type: string
          example: Claude Code
        channel:
          type: string
          enum:
            - app
            - api
            - mcp
        started:
          type: string
        last_activity:
          type: string
          description: >-
            Every report from the run moves it. A run silent for 24 hours can be
            taken over.
        ended:
          type:
            - string
            - 'null'
    WorkItemPost:
      type: object
      description: A linked post with its numbers.
      properties:
        feedback_id:
          type: integer
        title:
          type: string
        status:
          type: string
        type:
          type: string
        votes:
          type: integer
        impact_score:
          type: number
        user_priority:
          type: number
          description: The average user priority voters gave the post. 0 when nobody did.
    WorkItemDemand:
      type: object
      description: What the linked posts add up to.
      properties:
        posts:
          type: integer
        votes:
          type: integer
        impact_score_max:
          type:
            - number
            - 'null'
          description: '`null` without posts.'
        user_priority_avg:
          type:
            - number
            - 'null'
          description: Over the posts somebody rated. `null` when none is rated.
    WorkItemEvidence:
      type: object
      properties:
        evidence_id:
          type: integer
        text:
          type: string
        url:
          type:
            - string
            - 'null'
        channel:
          type: string
          enum:
            - app
            - api
            - mcp
        agent:
          type:
            - string
            - 'null'
        created:
          type: string
    WorkItemDocument:
      type: object
      description: >-
        A document of the work item: its spec, its plan, or a document your team
        linked as evidence. Read it with the documents endpoints.
      properties:
        document_id:
          type: integer
        role:
          type: string
          enum:
            - spec
            - plan
            - evidence
          description: >-
            `evidence` is a document your team linked to the work item in the
            dashboard. Ignore a role you do not know: the list may grow.
        title:
          type: string
        updated:
          type: string
    WorkItemPullRequest:
      type: object
      description: >-
        A pull request as the reports named it. The newest report decides its
        state.
      properties:
        url:
          type: string
        repository:
          type:
            - string
            - 'null'
        pr_number:
          type:
            - integer
            - 'null'
        branch:
          type:
            - string
            - 'null'
        state:
          type: string
          enum:
            - open
            - merged
            - closed
  responses:
    Unauthorized:
      description: Missing, malformed, or non-API-key credential
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key's user lacks the permission for this action
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such resource in this workspace
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Over 300 requests in 60 seconds
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer YOUR_API_KEY`. /v2 accepts no other method.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.