0
# Comments
1

2
Create and manage comments on pages and blocks for collaboration features.
3

4
## Capabilities
5

6
### Create Comment
7

8
Add a new comment to a page or block.
9

10
```typescript { .api }
11
/**
12
 * Create a new comment
13
 * @param args - Comment creation parameters
14
 * @returns Promise resolving to created comment
15
 */
16
comments.create(args: CreateCommentParameters): Promise<CreateCommentResponse>;
17

18
interface CreateCommentParameters {
19
  /** Parent page or block for the comment */
20
  parent: {
21
    type: "page_id";
22
    page_id: string;
23
  } | {
24
    type: "block_id";
25
    block_id: string;
26
  };
27
  /** Comment text */
28
  rich_text: RichTextItemResponse[];
29
}
30

31
type CreateCommentResponse = CommentObjectResponse;
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
// Comment on a page
38
const comment = await notion.comments.create({
39
  parent: { type: "page_id", page_id: "page-id" },
40
  rich_text: [
41
    {
42
      text: { content: "This is a great page!" },
43
    },
44
  ],
45
});
46

47
// Comment on a specific block
48
const blockComment = await notion.comments.create({
49
  parent: { type: "block_id", block_id: "block-id" },
50
  rich_text: [
51
    {
52
      text: { content: "Need to update this section." },
53
      annotations: { bold: true },
54
    },
55
  ],
56
});
57

58
// Comment with rich text formatting
59
const richComment = await notion.comments.create({
60
  parent: { type: "page_id", page_id: "page-id" },
61
  rich_text: [
62
    {
63
      text: { content: "Please review " },
64
    },
65
    {
66
      text: { content: "this section", link: { url: "https://example.com" } },
67
      annotations: { underline: true },
68
    },
69
    {
70
      text: { content: " by tomorrow." },
71
    },
72
  ],
73
});
74
```
75

76
### List Comments
77

78
Retrieve comments for a specific page or block.
79

80
```typescript { .api }
81
/**
82
 * List comments for a page or block
83
 * @param args - Comment list parameters
84
 * @returns Promise resolving to list of comments
85
 */
86
comments.list(args: ListCommentsParameters): Promise<ListCommentsResponse>;
87

88
interface ListCommentsParameters {
89
  /** ID of the page or block to get comments for */
90
  block_id: string;
91
  /** Pagination cursor */
92
  start_cursor?: string;
93
  /** Page size (max 100) */
94
  page_size?: number;
95
}
96

97
type ListCommentsResponse = {
98
  object: "list";
99
  results: CommentObjectResponse[];
100
  next_cursor: string | null;
101
  has_more: boolean;
102
  type: "comment";
103
  comment: Record<string, unknown>;
104
};
105
```
106

107
**Usage Examples:**
108

109
```typescript
110
// Get all comments for a page
111
const comments = await notion.comments.list({
112
  block_id: "page-id",
113
});
114

115
comments.results.forEach(comment => {
116
  console.log(`${comment.created_by.name}: ${comment.rich_text[0]?.text?.content}`);
117
});
118

119
// Paginated comment retrieval
120
const commentsPage = await notion.comments.list({
121
  block_id: "page-id",
122
  page_size: 25,
123
  start_cursor: "cursor-token",
124
});
125

126
// Get all comments with pagination
127
let cursor: string | undefined;
128
let allComments: CommentObjectResponse[] = [];
129

130
do {
131
  const response = await notion.comments.list({
132
    block_id: "page-id",
133
    start_cursor: cursor,
134
  });
135
  
136
  allComments.push(...response.results);
137
  cursor = response.next_cursor || undefined;
138
} while (cursor);
139
```
140

141
### Retrieve Comment
142

143
Get a specific comment by its ID.
144

145
```typescript { .api }
146
/**
147
 * Retrieve a comment by ID
148
 * @param args - Comment retrieval parameters
149
 * @returns Promise resolving to comment object
150
 */
151
comments.retrieve(args: GetCommentParameters): Promise<GetCommentResponse>;
152

153
interface GetCommentParameters {
154
  /** ID of the comment to retrieve */
155
  comment_id: string;
156
}
157

158
type GetCommentResponse = CommentObjectResponse;
159
```
160

161
**Usage Examples:**
162

163
```typescript
164
// Get a specific comment
165
const comment = await notion.comments.retrieve({
166
  comment_id: "comment-id-here",
167
});
168

169
console.log(comment.rich_text[0]?.text?.content); // Comment text
170
console.log(comment.created_time); // When comment was created
171
console.log(comment.created_by.name); // Who created the comment
172
```
173

174
## Types
175

176
```typescript { .api }
177
interface CommentObjectResponse {
178
  object: "comment";
179
  id: string;
180
  parent: {
181
    type: "page_id";
182
    page_id: string;
183
  } | {
184
    type: "block_id";
185
    block_id: string;
186
  };
187
  discussion_id: string;
188
  created_time: string;
189
  created_by: PartialUserObjectResponse;
190
  last_edited_time: string;
191
  rich_text: RichTextItemResponse[];
192
}
193

194
interface PartialCommentObjectResponse {
195
  object: "comment";
196
  id: string;
197
}
198
```