0
# Page Operations
1

2
Create, retrieve, and update pages within Notion workspaces. Pages can be standalone or part of databases.
3

4
## Capabilities
5

6
### Create Page
7

8
Create a new page in a Notion workspace, either as a standalone page or as a database entry.
9

10
```typescript { .api }
11
/**
12
 * Create a new page
13
 * @param args - Page creation parameters
14
 * @returns Promise resolving to created page
15
 */
16
pages.create(args: CreatePageParameters): Promise<CreatePageResponse>;
17

18
interface CreatePageParameters {
19
  /** Parent page or database for the new page */
20
  parent: {
21
    type: "page_id";
22
    page_id: string;
23
  } | {
24
    type: "database_id";
25
    database_id: string;
26
  };
27
  /** Page properties (required for database pages) */
28
  properties?: Record<string, PropertyValue>;
29
  /** Page content as an array of blocks */
30
  children?: BlockObjectRequest[];
31
  /** Page icon */
32
  icon?: {
33
    type: "emoji";
34
    emoji: string;
35
  } | {
36
    type: "external";
37
    external: { url: string };
38
  } | {
39
    type: "file";
40
    file: { url: string; expiry_time: string };
41
  };
42
  /** Page cover image */
43
  cover?: {
44
    type: "external";
45
    external: { url: string };
46
  } | {
47
    type: "file";
48
    file: { url: string; expiry_time: string };
49
  };
50
}
51

52
type CreatePageResponse = PageObjectResponse;
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
// Create a standalone page
59
const page = await notion.pages.create({
60
  parent: { type: "page_id", page_id: "parent-page-id" },
61
  properties: {
62
    title: {
63
      title: [{ text: { content: "My New Page" } }],
64
    },
65
  },
66
});
67

68
// Create a database page with properties
69
const databasePage = await notion.pages.create({
70
  parent: { type: "database_id", database_id: "database-id" },
71
  properties: {
72
    Name: {
73
      title: [{ text: { content: "Task Name" } }],
74
    },
75
    Status: {
76
      select: { name: "In Progress" },
77
    },
78
    Priority: {
79
      number: 3,
80
    },
81
  },
82
});
83

84
// Create page with content blocks
85
const pageWithContent = await notion.pages.create({
86
  parent: { type: "page_id", page_id: "parent-id" },
87
  properties: {
88
    title: { title: [{ text: { content: "Page with Content" } }] },
89
  },
90
  children: [
91
    {
92
      type: "paragraph",
93
      paragraph: {
94
        rich_text: [{ text: { content: "This is a paragraph." } }],
95
      },
96
    },
97
    {
98
      type: "heading_1",
99
      heading_1: {
100
        rich_text: [{ text: { content: "Heading 1" } }],
101
      },
102
    },
103
  ],
104
});
105
```
106

107
### Retrieve Page
108

109
Get a page by its ID, including its properties and metadata.
110

111
```typescript { .api }
112
/**
113
 * Retrieve a page by ID
114
 * @param args - Page retrieval parameters
115
 * @returns Promise resolving to page object
116
 */
117
pages.retrieve(args: GetPageParameters): Promise<GetPageResponse>;
118

119
interface GetPageParameters {
120
  /** ID of the page to retrieve */
121
  page_id: string;
122
  /** Specific properties to include in response */
123
  filter_properties?: string[];
124
}
125

126
type GetPageResponse = PageObjectResponse;
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
// Get a page
133
const page = await notion.pages.retrieve({ 
134
  page_id: "page-id-here" 
135
});
136

137
// Get page with specific properties only
138
const page = await notion.pages.retrieve({
139
  page_id: "page-id-here",
140
  filter_properties: ["Name", "Status"],
141
});
142
```
143

144
### Update Page
145

146
Update page properties, icon, cover, or archive status.
147

148
```typescript { .api }
149
/**
150
 * Update a page's properties
151
 * @param args - Page update parameters
152
 * @returns Promise resolving to updated page
153
 */
154
pages.update(args: UpdatePageParameters): Promise<UpdatePageResponse>;
155

156
interface UpdatePageParameters {
157
  /** ID of the page to update */
158
  page_id: string;
159
  /** Properties to update */
160
  properties?: Record<string, PropertyValue | null>;
161
  /** Archive the page */
162
  archived?: boolean;
163
  /** Update page icon */
164
  icon?: {
165
    type: "emoji";
166
    emoji: string;
167
  } | {
168
    type: "external";
169
    external: { url: string };
170
  } | {
171
    type: "file";
172
    file: { url: string; expiry_time: string };
173
  } | null;
174
  /** Update page cover */
175
  cover?: {
176
    type: "external";
177
    external: { url: string };
178
  } | {
179
    type: "file";
180
    file: { url: string; expiry_time: string };
181
  } | null;
182
}
183

184
type UpdatePageResponse = PageObjectResponse;
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
// Update page properties
191
const updatedPage = await notion.pages.update({
192
  page_id: "page-id",
193
  properties: {
194
    Status: {
195
      select: { name: "Complete" },
196
    },
197
    Priority: {
198
      number: 5,
199
    },
200
  },
201
});
202

203
// Archive a page
204
const archivedPage = await notion.pages.update({
205
  page_id: "page-id",
206
  archived: true,
207
});
208

209
// Update page icon and cover
210
const updatedPage = await notion.pages.update({
211
  page_id: "page-id", 
212
  icon: {
213
    type: "emoji",
214
    emoji: "📝",
215
  },
216
  cover: {
217
    type: "external",
218
    external: { url: "https://example.com/cover.jpg" },
219
  },
220
});
221
```
222

223
### Retrieve Page Property
224

225
Get the value of a specific page property, particularly useful for properties with large values.
226

227
```typescript { .api }
228
/**
229
 * Retrieve a specific page property
230
 * @param args - Page property retrieval parameters
231
 * @returns Promise resolving to property value
232
 */
233
pages.properties.retrieve(args: GetPagePropertyParameters): Promise<GetPagePropertyResponse>;
234

235
interface GetPagePropertyParameters {
236
  /** ID of the page */
237
  page_id: string;
238
  /** ID of the property to retrieve */
239
  property_id: string;
240
  /** Pagination cursor for large property values */
241
  start_cursor?: string;
242
  /** Page size for paginated results */
243
  page_size?: number;
244
}
245

246
type GetPagePropertyResponse = PropertyItemObjectResponse | PropertyItemListResponse;
247
```
248

249
**Usage Examples:**
250

251
```typescript
252
// Get a specific property
253
const property = await notion.pages.properties.retrieve({
254
  page_id: "page-id",
255
  property_id: "property-id",
256
});
257

258
// Get paginated property results
259
const propertyPage = await notion.pages.properties.retrieve({
260
  page_id: "page-id",
261
  property_id: "property-id",
262
  start_cursor: "cursor-token",
263
  page_size: 100,
264
});
265
```
266

267
## Types
268

269
```typescript { .api }
270
interface PageObjectResponse {
271
  object: "page";
272
  id: string;
273
  created_time: string;
274
  created_by: PartialUserObjectResponse;
275
  last_edited_time: string;
276
  last_edited_by: PartialUserObjectResponse;
277
  archived: boolean;
278
  icon?: {
279
    type: "emoji";
280
    emoji: string;
281
  } | {
282
    type: "external";
283
    external: { url: string };
284
  } | {
285
    type: "file";
286
    file: { url: string; expiry_time: string };
287
  };
288
  cover?: {
289
    type: "external";
290
    external: { url: string };
291
  } | {
292
    type: "file";
293
    file: { url: string; expiry_time: string };
294
  };
295
  properties: Record<string, PropertyItemObjectResponse>;
296
  parent: {
297
    type: "database_id";
298
    database_id: string;
299
  } | {
300
    type: "page_id";
301
    page_id: string;
302
  } | {
303
    type: "workspace";
304
    workspace: true;
305
  };
306
  url: string;
307
  public_url?: string;
308
}
309

310
interface PartialPageObjectResponse {
311
  object: "page";
312
  id: string;
313
}
314

315
type PropertyValue = 
316
  | { title: RichTextItemResponse[] }
317
  | { rich_text: RichTextItemResponse[] }
318
  | { number: number | null }
319
  | { select: { name: string } | null }
320
  | { multi_select: { name: string }[] }
321
  | { date: { start: string; end?: string; time_zone?: string } | null }
322
  | { checkbox: boolean }
323
  | { url: string | null }
324
  | { email: string | null }
325
  | { phone_number: string | null }
326
  | { relation: { id: string }[] }
327
  | { people: PartialUserObjectResponse[] }
328
  | { files: FileObjectResponse[] };
329

330
interface PropertyItemListResponse {
331
  object: "list";
332
  results: PropertyItemObjectResponse[];
333
  next_cursor: string | null;
334
  has_more: boolean;
335
  type: string;
336
  property_item: Record<string, unknown>;
337
}
338
```