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

# Create a work item

> Creates a work item. It starts as `needs_decision`: a person decides when work starts.

Send the body as JSON. `feedback_ids` and `evidence` must be JSON arrays; an XML body cannot carry a list, so it is answered with `400 validation_error`.

A post belongs to at most one work item. If another work item already holds one of `feedback_ids`, nothing is created and the answer is `409 feedback_already_linked`, naming that work item.



## OpenAPI

````yaml /docs/api/openapi-v2.yaml post /work-items
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:
    post:
      tags:
        - Work item
      summary: Create a work item
      description: >-
        Creates a work item. It starts as `needs_decision`: a person decides
        when work starts.


        Send the body as JSON. `feedback_ids` and `evidence` must be JSON
        arrays; an XML body cannot carry a list, so it is answered with `400
        validation_error`.


        A post belongs to at most one work item. If another work item already
        holds one of `feedback_ids`, nothing is created and the answer is `409
        feedback_already_linked`, naming that work item.
      operationId: v2-create-work-item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 255
                brief:
                  type: string
                  maxLength: 50000
                  description: >-
                    Markdown. The task, as the person or agent working on it
                    will read it.
                priority:
                  type: integer
                  minimum: 0
                  maximum: 4
                  default: 0
                  description: >-
                    The user-priority scale of posts: 0 is no priority, 4
                    critical.
                component:
                  type: string
                  maxLength: 64
                  description: >-
                    A component key defined in this workspace. An unknown key is
                    rejected with `invalid_argument`.
                feedback_ids:
                  type: array
                  maxItems: 100
                  items:
                    type: integer
                  description: >-
                    Posts this work item answers. Each must be a post of this
                    workspace that no other work item holds.
                evidence:
                  type: array
                  maxItems: 100
                  description: 'What supports doing this: a call, a ticket, a number.'
                  items:
                    type: object
                    required:
                      - text
                    properties:
                      text:
                        type: string
                        maxLength: 5000
                      url:
                        type: string
                        maxLength: 2048
                        description: http or https.
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkItemEnvelope'
        '400':
          description: >-
            A field is malformed (`validation_error`), or the component is
            unknown (`invalid_argument`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: One of `feedback_ids` is not a post of this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`feedback_already_linked`: another work item holds one of the posts'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    WorkItemEnvelope:
      type: object
      properties:
        status:
          type: string
        data:
          $ref: '#/components/schemas/WorkItem'
    Error:
      type: object
      properties:
        status:
          type: string
          example: error
        data:
          type: object
          properties:
            key:
              type: string
            message:
              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'
    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.