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

# Create a workspace plan task comment

> Add a comment to a workspace plan task. The comment appears in the task's comment thread and notifies the thread participants by email, the same as a comment added in Dock.

To attach files, upload each one first with [Create a file](/api-reference/endpoint/files/create-a-file) (PUT the bytes to the returned upload URL), then pass the file IDs in `fileIds` (up to 5). Supported file types are listed on Create a file.

The comment is authored by the API key's user unless `userId` or `userEmail` is provided. When both are provided, `userId` is used. An email that does not belong to an existing user creates a client user

export const RateLimit = ({perMinute = 120}) => <Info>
    This endpoint is rate limited to <strong>{perMinute} requests per minute</strong> per
    company. See <a href="/api-reference/rate-limits">Rate limits</a> for details.
  </Info>;

<RateLimit />


## OpenAPI

````yaml post /workspace-plan-tasks/{id}/comments
openapi: 3.1.0
info:
  title: Dock API
  description: >-
    The Dock API is a RESTful API that allows you to interact with Dock in a
    programmatic way
  termsOfService: https://www.dock.us/legal/terms
  contact:
    name: API Support
    email: developers@dock.us
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://api.dock.us/{version}
    description: Production server
    variables:
      version:
        default: v1
        enum:
          - v1
security:
  - bearerAuth: []
tags:
  - name: Status check
    description: API to check if the API is up
  - name: Accounts
    description: API to manage accounts
  - name: Assets
    description: API to manage assets
  - name: Asset share links
    description: API to retrieve asset share links
  - name: Files
    description: API to manage files
  - name: Forms
    description: API to retrieve forms and their responses
  - name: Meetings
    description: API to manage meetings and call transcripts
  - name: Tags
    description: API to manage tags
  - name: Users
    description: API to manage users
  - name: Workspaces
    description: API to manage workspaces
  - name: Templates
    description: API to manage templates
  - name: Workspace pages
    description: API to manage workspace pages
  - name: Workspace plans
    description: API to manage workspace plans
  - name: Workspace plan tasks
    description: API to manage workspace plan tasks
  - name: Workspace sections
    description: API to manage workspace sections
paths:
  /workspace-plan-tasks/{id}/comments:
    post:
      tags:
        - Workspace plan tasks
      description: >-
        Add a comment to a workspace plan task. The comment appears in the
        task's comment thread and notifies the thread participants by email, the
        same as a comment added in Dock.


        To attach files, upload each one first with [Create a
        file](/api-reference/endpoint/files/create-a-file) (PUT the bytes to the
        returned upload URL), then pass the file IDs in `fileIds` (up to 5).
        Supported file types are listed on Create a file.


        The comment is authored by the API key's user unless `userId` or
        `userEmail` is provided. When both are provided, `userId` is used. An
        email that does not belong to an existing user creates a client user
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/workspacePlanTaskCommentProperties'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                  maxLength: 100000
                  description: >-
                    Comment text as HTML rich text, the same format `body` is
                    returned in. Supports paragraphs (`<p>`, `<br>`),
                    `<strong>`/`<b>`, `<em>`/`<i>`, `<u>`, text color
                    (`style="color: …"`), links and `<ul>`/`<ol>` lists. Other
                    blocks such as tables and code are kept as plain paragraphs.
                    Content outside a `<p>` (for example Asana's
                    `<body>One\nTwo</body>` or plain text) is split into one
                    paragraph per line, and blank lines are kept. Inside a
                    `<p>`, newlines are ordinary whitespace. Required unless
                    `fileIds` is provided
                  example: >-
                    <p>Uploaded the <strong>signed</strong>
                    contract</p><ul><li>Pages 1–3 initialed</li></ul>
                fileIds:
                  type: array
                  maxItems: 5
                  uniqueItems: true
                  description: >-
                    IDs of files uploaded with Create a file to attach to the
                    comment
                  items:
                    type: string
                    example: RiHO4e0Ju3DS
                userId:
                  type: string
                  description: >-
                    ID of the user to author the comment as. Takes precedence
                    over `userEmail`
                  example: RiHO4e0Ju3DS
                userEmail:
                  type: string
                  format: email
                  description: >-
                    Email of the user to author the comment as. Creates a client
                    user when no user has this email
                  example: jane@acme.com
      responses:
        '201':
          description: The created workspace plan task comment
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      workspacePlanTaskComment:
                        $ref: '#/components/schemas/WorkspacePlanTaskComment'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    id:
      name: id
      in: path
      example: RiHO4e0Ju3DS
      required: true
      description: Unique identifier
      schema:
        type: string
        example: RiHO4e0Ju3DS
    workspacePlanTaskCommentProperties:
      name: properties
      in: query
      description: >-
        Select the comment properties to return. Comments return only `id` and
        `object` unless other properties are requested. Request
        `author.<property>` (for example `author.email`) to include the author,
        and `files.<property>` (for example `files.downloadUrl`) to include the
        attached files; both nested objects always carry their `id`, `object`
        and `url`
      schema:
        type: array
        items:
          type: string
          enum:
            - taskId
            - body
            - author.createdAt
            - author.updatedAt
            - author.firstName
            - author.lastName
            - author.avatar
            - author.email
            - author.name
            - files.name
            - files.thumbnail
            - files.size
            - files.downloadUrl
            - files.expiresAt
            - files.uploadStatus
            - files.mimeType
            - createdAt
            - updatedAt
  schemas:
    WorkspacePlanTaskComment:
      allOf:
        - $ref: '#/components/schemas/BaseObject'
        - type: object
          properties:
            object:
              type: string
              description: Type of the object
              enum:
                - workspace-plan-task-comment
              example: workspace-plan-task-comment
              readOnly: true
            taskId:
              type: string
              description: ID of the workspace plan task the comment belongs to
              example: RiHO4e0Ju3DS
              readOnly: true
            body:
              type: string
              description: >-
                Comment text as HTML rich text (the same format as `richText`
                custom field values): paragraphs, bold, italic, underline, text
                color, links and bulleted/numbered lists. Mentions render as
                `@Name`. Empty for a comment that only has files
              example: >-
                <p>Uploaded the <span style="font-weight:700">signed</span>
                contract @Jane Doe</p>
            author:
              description: >-
                User who wrote the comment, as a
                [user](/api-reference/endpoint/users/retrieve-a-user) object.
                Requested with `author.<property>`. `null` for comments synced
                from a connected ticketing integration
              nullable: true
              allOf:
                - $ref: '#/components/schemas/User'
            files:
              type: array
              description: >-
                Files attached to the comment, as the same file objects returned
                by Retrieve a file. Requested with `files.<property>`: each file
                has `id`, `object` and `url` (the file's API URL) plus the
                requested properties, such as `downloadUrl`. File ids passed in
                `fileIds` come back here unchanged. Download links expire; read
                the comment again or retrieve the file for a fresh link
              readOnly: true
              items:
                $ref: '#/components/schemas/File'
    BaseObject:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/Id'
        updatedAt:
          type: string
          format: date-time
          description: Last updated date
          example: '2021-01-01T00:00:00.000Z'
          readOnly: true
        createdAt:
          type: string
          format: date-time
          description: Created at date
          example: '2021-01-01T00:00:00.000Z'
          readOnly: true
    User:
      allOf:
        - $ref: '#/components/schemas/BaseObject'
        - type: object
          properties:
            object:
              type: string
              description: Type of the object
              enum:
                - user
              example: user
              readOnly: true
            url:
              type: string
              example: https://api.dock.us/v1/users/RiHO4e0Ju3DS
              description: URL to the resource
              readOnly: true
            firstName:
              type: string
              description: First name of the user
              example: John
              nullable: true
            lastName:
              type: string
              description: Last name of the user
              example: Doe
              nullable: true
            avatar:
              type: string
              format: uri
              description: Avatar of the user
              example: https://dock.us/avatar.png
              nullable: true
            email:
              type: string
              description: Email of the user
              example: john.doe@example.com
            name:
              type: string
              description: Name of the user
              example: John Doe
    File:
      allOf:
        - $ref: '#/components/schemas/BaseObject'
        - type: object
          properties:
            object:
              type: string
              description: Type of the object
              enum:
                - file
              example: file
              readOnly: true
            name:
              type: string
              description: Name of the file
              example: contract.pdf
              nullable: true
            thumbnail:
              type: string
              description: Thumbnail URL for the file when available
              example: >-
                https://storage.googleapis.com/dock-production-private/thumbnails/contract.png
              nullable: true
            size:
              type: integer
              description: File size in bytes
              example: 24576
              nullable: true
            url:
              type: string
              description: URL to the resource
              example: https://api.dock.us/v1/files/RiHO4e0Ju3DS
              readOnly: true
            downloadUrl:
              type: string
              description: >-
                Download link for the file's contents. Private files get a
                presigned link valid until `expiresAt`; retrieve the file again
                for a fresh link instead of storing it. `null` until the upload
                has completed
              example: >-
                https://storage.googleapis.com/dock-production-private/signed-url
              nullable: true
            expiresAt:
              type: string
              format: date-time
              description: When `downloadUrl` expires. `null` for links that do not expire
              example: '2026-06-12T12:00:00.000Z'
              nullable: true
            uploadStatus:
              type: string
              description: >-
                Upload/processing state of the file. Files created via POST
                /files stay `in_progress` until their bytes are uploaded and an
                asset is created from them; converted office files stay
                `in_progress` until conversion completes.
              enum:
                - success
                - in_progress
                - failed
              example: success
              nullable: true
            mimeType:
              type: string
              description: MIME type of the file
              example: application/pdf
              nullable: true
    Id:
      type: string
      description: Id of the object
      example: RiHO4e0Ju3DS
      readOnly: true
  responses:
    '400':
      description: >-
        The server cannot or will not process the request due to something that
        is perceived to be a client error (e.g., malformed request syntax,
        invalid request message framing, or deceptive request routing)
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - BAD_REQUEST
                    description: A short code indicating the error code returned
                    example: BAD_REQUEST
                  message:
                    type: string
                    description: A human readable explanation of what went wrong
                    example: >-
                      The request could not be understood or was missing
                      required parameters
                required:
                  - code
                  - message
            required:
              - error
    '401':
      description: >-
        Although the HTTP standard specifies "unauthorized", semantically this
        response means "unauthenticated". That is, the client must authenticate
        itself to get the requested response
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - UNAUTHORIZED
                    description: A short code indicating the error code returned
                    example: UNAUTHORIZED
                  message:
                    type: string
                    description: A human readable explanation of what went wrong
                    example: >-
                      Access denied. You are not authorized to access this
                      resource
                required:
                  - code
                  - message
            required:
              - error
    '403':
      description: >-
        The client does not have access rights to the content; that is, it is
        unauthorized, so the server is refusing to give the requested resource.
        Unlike 401 Unauthorized, the client's identity is known to the server
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - FORBIDDEN
                    description: A short code indicating the error code returned
                    example: FORBIDDEN
                  message:
                    type: string
                    description: A human readable explanation of what went wrong
                    example: Access to this resource is restricted
                required:
                  - code
                  - message
            required:
              - error
    '404':
      description: The server cannot find the requested resource
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - NOT_FOUND
                    description: A short code indicating the error code returned
                    example: NOT_FOUND
                  message:
                    type: string
                    description: A human readable explanation of what went wrong
                    example: The requested resource could not be found
                required:
                  - code
                  - message
            required:
              - error
    '429':
      description: >-
        The user has sent too many requests in a given amount of time ("rate
        limiting")
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: A short code indicating the error code returned
                    example: RATE_LIMIT_EXCEEDED
                  message:
                    type: string
                    description: A human readable explanation of what went wrong
                    example: Rate limit exceeded. Please try again later
                required:
                  - code
                  - message
            required:
              - error
    '500':
      description: The server has encountered a situation it does not know how to handle
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - INTERNAL_SERVER_ERROR
                    description: A short code indicating the error code returned
                    example: INTERNAL_SERVER_ERROR
                  message:
                    type: string
                    description: A human readable explanation of what went wrong
                    example: >-
                      The server has encountered a situation it does not know
                      how to handle
                required:
                  - code
                  - message
            required:
              - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

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