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

# Create a task

> Create a task with optional Markdown description and acceptance criteria, type task or bug, a fixed status, assignee, priority, start date and due date. Type defaults to task and status to todo. Reuse the `Idempotency-Key` header on retries.

Write access: a member/administrator with a write-enabled credential, or an authorized signed-in user.

Create a task with optional Markdown description and acceptance criteria, type task or bug, a fixed status, assignee, priority, start date and due date. Type defaults to task and status to todo. Reuse the `Idempotency-Key` header on retries.

Creation requires title and defaults type to task, status to todo, priority to none, assignee and dates to null, and Markdown fields to empty. Active human assignees only. Mentions and assignments respect in-app notification preferences.

MCP clients can use [`create_task`](https://www.mill.fyi/mcp-reference/create_task) for this operation.

[Request conventions](https://www.mill.fyi/api-reference/overview.md) · [API keys](https://www.mill.fyi/api-keys.md) · [MCP connections](https://www.mill.fyi/mcp-connections.md)


## OpenAPI

````yaml api-reference/openapi.json POST /api/boards/{boardId}/tasks
openapi: 3.1.0
info:
  title: Mill HTTP API
  version: 1.0.6
  description: >-
    All registered task-board, account, OAuth, MCP transport and health
    operations. MCP tool schemas come from runtime validators; account
    operations follow their server handlers. Example data is fictional.
    Generation imports routes without issuing requests or connecting to a
    database.
servers:
  - url: https://mill-api.example.com
security: []
paths:
  /api/boards/{boardId}/tasks:
    post:
      tags:
        - Tasks
      summary: Create a task
      description: >-
        Create a task with optional Markdown description and acceptance
        criteria, type task or bug, a fixed status, assignee, priority, start
        date and due date. Type defaults to task and status to todo. Reuse the
        `Idempotency-Key` header on retries.


        Creation requires title and defaults type to task, status to todo,
        priority to none, assignee and dates to null, and Markdown fields to
        empty. Active human assignees only. Mentions and assignments respect
        in-app notification preferences.


        Write access: a member/administrator with a write-enabled credential, or
        an authorized signed-in user.
      operationId: post_api_boards_by_boardId_tasks
      parameters:
        - name: boardId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            The boardId from the corresponding list, record or authorization
            response.
        - name: Origin
          in: header
          required: false
          schema:
            type: string
            format: uri
          description: >-
            The exact configured Mill UI origin. Required for browser mutations
            carrying session cookies.
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            minLength: 8
            maxLength: 128
            pattern: ^[A-Za-z0-9._:-]+$
          description: >-
            Reuse the same key and exact request bytes for retries of one
            logical mutation; different content conflicts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - task
                    - bug
                title:
                  type: string
                  minLength: 1
                  maxLength: 300
                description:
                  type: string
                  maxLength: 100000
                acceptanceCriteria:
                  type: string
                  maxLength: 100000
                assigneeId:
                  anyOf:
                    - type: string
                      format: uuid
                      pattern: >-
                        ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                    - type: 'null'
                priority:
                  type: string
                  enum:
                    - none
                    - low
                    - medium
                    - high
                    - urgent
                status:
                  type: string
                  enum:
                    - backlog
                    - todo
                    - in_progress
                    - in_review
                    - done
                    - wont_do
                startDate:
                  anyOf:
                    - type: string
                      format: date
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                    - type: 'null'
                dueDate:
                  anyOf:
                    - type: string
                      format: date
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
                    - type: 'null'
              required:
                - title
              additionalProperties: false
            example:
              title: Verify database restore
              description: Restore a recent backup into an isolated database.
              acceptanceCriteria: |-
                - Confirm task and comment counts match
                - Record the result
              type: task
              priority: high
              status: todo
              assigneeId: 66666666-6666-4666-8666-666666666666
              startDate: '2027-01-18'
              dueDate: '2027-01-20'
      responses:
        '201':
          description: >-
            Successful response. Examples are illustrative; field values vary by
            record.
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    type: object
                    properties:
                      id:
                        type: string
                      boardId:
                        type: string
                      identifier:
                        type: string
                      title:
                        type: string
                      description:
                        type: string
                      acceptanceCriteria:
                        type: string
                      type:
                        type: string
                      status:
                        type: string
                      priority:
                        type: string
                      assigneeId:
                        type: string
                      startDate:
                        type: string
                      dueDate:
                        type: string
                      version:
                        type: integer
                      statusChangedAt:
                        type: string
                      createdAt:
                        type: string
                      updatedAt:
                        type: string
                      createdBy:
                        type: string
                    additionalProperties: true
                additionalProperties: true
                description: >-
                  Illustrative response shape. Fields can be absent in alternate
                  successful flows; see the operation description and example.
              example:
                task:
                  id: 22222222-2222-4222-8222-222222222222
                  boardId: 11111111-1111-4111-8111-111111111111
                  identifier: ENG-1
                  title: Verify database restore
                  description: Restore a recent backup into an isolated database.
                  acceptanceCriteria: |-
                    - Confirm task and comment counts match
                    - Record the result
                  type: task
                  status: todo
                  priority: high
                  assigneeId: 66666666-6666-4666-8666-666666666666
                  startDate: '2027-01-18'
                  dueDate: '2027-01-20'
                  version: 1
                  statusChangedAt: '2027-01-18T09:30:00.000Z'
                  createdAt: '2027-01-18T09:30:00.000Z'
                  updatedAt: '2027-01-18T09:30:00.000Z'
                  createdBy: 66666666-6666-4666-8666-666666666666
        default:
          description: >-
            Request failure. Inspect code, message and requestId; respect
            Retry-After on HTTP 429.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
        - sessionCookie: []
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - requestId
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal or team Mill REST API key
    sessionCookie:
      type: apiKey
      in: cookie
      name: mill_session
      description: >-
        Signed-in human browser session; mutation requests also need the exact
        UI Origin

````

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