discussion(discussionId:), or a page of them with discussions. threadDiscussion(threadDiscussionId:) still resolves. Prefer discussion for a new integration. Discussion IDs use the thd_ prefix.
For TypeScript, the GraphQL SDK gives you a fully typed client for these operations.
threadDiscussion:readto fetchdiscussionanddiscussionsthreadDiscussionMessage:readto fetchmessages
List discussions
discussions takes filters, sortBy, first, and after. Sort with sortBy: field is CREATED_AT, LAST_ACTIVITY_AT, or UPDATED_AT, and direction is ASC or DESC.
filters accepts:
- statuses:
OPENorRESOLVED - agentStatuses:
UNKNOWN,IDLE,IN_PROGRESS,TOOL_CALL_APPROVAL_PENDING, orCONNECTION_PENDING. A resolved discussion keeps the agent status it had when it was resolved. - threadIds: discussions on those threads, including workflow tasks when
isWorkflowTaskis unset - createdByUserIds: the user who created the discussion
- participatedByUserIds: a user who has posted a message in it
- discussionTypes:
EMAIL,SLACK,CURSOR_WORKSPACE_BACKGROUND_AGENT, orAGENT_SESSION - agentTypes:
PLAIN_SIDEKICK, orCUSTOM_AGENTfor an agent you connect - agentMachineUserIds: discussions run by those agent machine users
- isUnread: unread agent responses when
true, read ones whenfalse - createdBySystem: discussions a system actor created, such as a workflow, when
true - isWorkflowTask: Sidekick Agent tasks started by an
ask_sidekickworkflow step whentrue. Passfalseto leave those tasks out. - sourceEntityIds: discussions started from those entities
- sourceEntityTypes: the entity type for
sourceEntityIds - sourcePageLinks: the page the discussion was started from
- lastActivityAtAfter and lastActivityAtBefore: ISO 8601 bounds on the latest message
- and, or, not: combine the filters above
discussions with threadIds and no isWorkflowTask filter includes workflow tasks. Thread.threadDiscussions returns the discussions on that thread and leaves workflow tasks out.
Query
Variables
Get a discussion by ID
discussion loads one discussion, including its messages. Select visibility to see who can open it: WORKSPACE is every user in the workspace, and USER is the user who created it. The field is null until set.
Query
Variables
Messages
messages returns the discussion’s messages. Pass first, after, last, or before to page through them.
Each message includes text, createdBy, entryType, entry, attachments, and workspaceFiles. attachments is for email, Slack, and Cursor messages. workspaceFiles is for Sidekick Agent session messages.
entry is one of seven payloads. entryType names which one you received:
- ThreadDiscussionMessageEntryPayload: the message body
- ThreadDiscussionToolCallEntryPayload: a tool call
- ThreadDiscussionApprovalRequestEntryPayload: a Sidekick Agent approval
- ThreadDiscussionToolCallApprovalEntryPayload: an approval on one tool call an agent reported
- ThreadDiscussionConnectRequestEntryPayload: a request to connect a Sidekick Agent tool
- ThreadDiscussionQuestionEntryPayload: a Sidekick Agent question card
- ThreadDiscussionTurnStoppedEntryPayload: a stopped turn
toolCallId, service, op, description, args, status, error, durationMs, and response. status is PENDING, then SUCCESS or ERROR. toolCallId is null on a Sidekick Agent call. service is null on a call an agent reported.
response is the JSON-encoded result of a successful Sidekick Agent write. It is null for a read, a failed call, an oversized result, and a call an agent reported.
What the Sidekick Agent reads
The Sidekick Agent reads discussions with three tools.discussion.get returns metadata for one discussion. discussion.list returns a list of discussions. discussion.messages returns message text, authors, and files.
Each tool returns null when the discussion is missing or inaccessible. It also returns null when the linked thread is not readable, or when visibility is USER and the sender is not the creator.
thread.timeline returns discussion entry metadata. Message text comes from discussion.messages.
A restricted workflow session can always call Plain’s read operations. See Add a Sidekick Agent action.
