Create, update & delete discussions

A discussion is a standalone, project-scoped conversation thread — a place for a topic that isn’t tied to a single record. Discussions are Discussion objects in the API, and they live in a workspace (Project). Once a thread exists, replies are posted as comments with category: DISCUSSION (see Create, edit & delete comments).

• Use createDiscussion to seed a new thread with a title and an opening body.
• Use updateDiscussion to rename a thread — it edits the title only; the body is fixed once created.
• Use deleteDiscussion to remove a thread. Unlike a comment delete, this is a hard delete.

To read discussions back, use the discussion query paths. The Discussion.comments field is deprecated — load replies with commentList(category: DISCUSSION) instead.

createDiscussion

Create a discussion in a workspace. The opening message is supplied as both html (rich content, sanitized server-side) and text (the plain-text fallback). The mutation returns the created Discussion.

Request

mutation CreateDiscussion {
  createDiscussion(
    input: {
      projectId: "project_123"
      title: "Q3 launch retro"
      html: "<p>What went well, what didn't?</p>"
      text: "What went well, what didn't?"
    }
  ) {
    id
    title
    html
    text
    createdAt
    user {
      id
      fullName
    }
    project {
      id
      name
    }
  }
}

Parameters

CreateDiscussionInput

The body (html / text) is set once at creation and is immutable afterward — updateDiscussion changes only the title. To revise the opening message, delete the thread and create a new one, or post a follow-up comment.

Response

{
  "data": {
    "createDiscussion": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Q3 launch retro",
      "html": "<p>What went well, what didn't?</p>",
      "text": "What went well, what didn't?",
      "createdAt": "2026-05-29T14:02:11.000Z",
      "user": {
        "id": "clm4n8a1b000108l0c2d3e4f5",
        "fullName": "Dana Rao"
      },
      "project": {
        "id": "clm4n7zzz000008l0a1b2c3d4",
        "name": "Marketing"
      }
    }
  }
}

Returns

Returns the created Discussion.

Mentions, images & attachments

@mentions, inline images, and file attachments all travel inside the html field of the opening message — there are no separate arguments for them. To mention a user, include an anchor whose href is #view-profile-<userId>; the server rewrites it into a mention and notifies that user. The same convention applies when posting comment replies (see Create, edit & delete comments).

Errors

updateDiscussion

Rename a discussion. This is the only mutable field: UpdateDiscussionInput carries just id and an optional title. The mutation returns the updated Discussion.

Request

mutation UpdateDiscussion {
  updateDiscussion(input: { id: "discussion_123", title: "Q3 launch retro (final)" }) {
    id
    title
    updatedAt
  }
}

Parameters

UpdateDiscussionInput

There is no editDiscussion mutation, and there is no way to change html / text, projectId, or any other field through this call — only the title.

Response

{
  "data": {
    "updateDiscussion": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Q3 launch retro (final)",
      "updatedAt": "2026-05-29T15:18:44.000Z"
    }
  }
}

Returns

Returns the updated Discussion.

Errors

deleteDiscussion

Remove a discussion thread. This is a hard delete: before the row is removed, its reply chains are unlinked (threaded comment replies have their parentId cleared to release the foreign-key constraint), and a snapshot of the discussion is written to the organization’s Trash. The mutation returns a MutationResult.

This differs from deleteComment, which is a soft delete that keeps the row and blanks its body — see Create, edit & delete comments.

Request

deleteDiscussion takes the discussion id directly (not an input object) and returns a MutationResult.

mutation DeleteDiscussion {
  deleteDiscussion(id: "discussion_123") {
    success
    operationId
  }
}

Parameters

Response

{
  "data": {
    "deleteDiscussion": {
      "success": true,
      "operationId": "clm4n8qwx000008l0g4oxdqn7"
    }
  }
}

Returns

Errors

Discussion type

The fields available on a Discussion. The comment thread itself is loaded separately via commentList(category: DISCUSSION) — the Discussion.comments field is deprecated and should not be used.

Permissions

All three mutations require the caller to be a member of the discussion’s workspace, and they deny VIEW_ONLY and COMMENT_ONLY access levels. The workspace must be active (not archived).

Related

• Comments overview — the Comment type, CommentCategory, threading, and read state.
• Query discussions — fetch a single thread, list threads, or page through a workspace’s threads.
• Create, edit & delete comments — post the replies that hang off a discussion.
• Query comments — load a discussion’s replies with commentList.
• Comment & discussion subscriptions — stream discussion and comment changes in real time.