0
# API Endpoints
1
2
Complete interface to all Notion API endpoints including databases, pages, blocks, users, search, comments, and file uploads. Each endpoint provides CRUD operations with proper parameter handling and supports both synchronous and asynchronous usage.
3
4
## Capabilities
5
6
### Database Operations
7
8
Interface for working with Notion databases including querying, creating, updating, and retrieving database information.
9
10
```python { .api }
11
class DatabasesEndpoint:
12
"""Database operations endpoint."""
13
14
def query(self, database_id, **kwargs):
15
"""
16
Get a list of Pages contained in the database.
17
18
Parameters:
19
- database_id: str, database ID
20
- filter: dict, query filter conditions
21
- sorts: list, sort configuration
22
- start_cursor: str, pagination cursor
23
- page_size: int, number of results per page (max 100)
24
- archived: bool, whether to include archived pages
25
- in_trash: bool, whether to include pages in trash
26
- filter_properties: list, properties to include in response
27
- auth: str, optional auth token for this request
28
29
Returns:
30
Dict with 'results' list of page objects and pagination info
31
"""
32
33
def retrieve(self, database_id, **kwargs):
34
"""
35
Retrieve a Database object using the ID specified.
36
37
Parameters:
38
- database_id: str, database ID
39
- auth: str, optional auth token for this request
40
41
Returns:
42
Database object dict
43
"""
44
45
def create(self, **kwargs):
46
"""
47
Create a database as a subpage in the specified parent page.
48
49
Parameters:
50
- parent: dict, parent page reference
51
- title: list, database title as rich text
52
- description: list, database description as rich text
53
- properties: dict, database schema properties
54
- icon: dict, database icon
55
- cover: dict, database cover image
56
- is_inline: bool, whether database is inline
57
- auth: str, optional auth token for this request
58
59
Returns:
60
Created database object dict
61
"""
62
63
def update(self, database_id, **kwargs):
64
"""
65
Update an existing database as specified by the parameters.
66
67
Parameters:
68
- database_id: str, database ID
69
- properties: dict, updated database schema properties
70
- title: list, updated database title as rich text
71
- description: list, updated database description as rich text
72
- icon: dict, updated database icon
73
- cover: dict, updated database cover image
74
- is_inline: bool, whether database is inline
75
- archived: bool, whether to archive the database
76
- in_trash: bool, whether to move database to trash
77
- auth: str, optional auth token for this request
78
79
Returns:
80
Updated database object dict
81
"""
82
83
def list(self, **kwargs):
84
"""
85
List all Databases shared with the authenticated integration.
86
87
DEPRECATED: This endpoint is deprecated.
88
89
Parameters:
90
- start_cursor: str, pagination cursor
91
- page_size: int, number of results per page
92
- auth: str, optional auth token for this request
93
94
Returns:
95
Dict with 'results' list of database objects and pagination info
96
"""
97
```
98
99
### Page Operations
100
101
Interface for creating, retrieving, and updating Notion pages and their properties.
102
103
```python { .api }
104
class PagesEndpoint:
105
"""Page operations endpoint."""
106
107
# Sub-endpoint for page properties
108
properties: PagesPropertiesEndpoint
109
110
def create(self, **kwargs):
111
"""
112
Create a new page in the specified database or as a child of an existing page.
113
114
Parameters:
115
- parent: dict, parent reference (database_id or page_id)
116
- properties: dict, page property values
117
- children: list, child block objects to add
118
- icon: dict, page icon
119
- cover: dict, page cover image
120
- auth: str, optional auth token for this request
121
122
Returns:
123
Created page object dict
124
"""
125
126
def retrieve(self, page_id, **kwargs):
127
"""
128
Retrieve a Page object using the ID specified.
129
130
Parameters:
131
- page_id: str, page ID
132
- filter_properties: list, properties to include in response
133
- auth: str, optional auth token for this request
134
135
Returns:
136
Page object dict
137
"""
138
139
def update(self, page_id, **kwargs):
140
"""
141
Update page property values for the specified page.
142
143
Parameters:
144
- page_id: str, page ID
145
- properties: dict, updated property values
146
- icon: dict, updated page icon
147
- cover: dict, updated page cover image
148
- archived: bool, whether to archive the page
149
- in_trash: bool, whether to move page to trash
150
- auth: str, optional auth token for this request
151
152
Returns:
153
Updated page object dict
154
"""
155
156
class PagesPropertiesEndpoint:
157
"""Page property operations endpoint."""
158
159
def retrieve(self, page_id, property_id, **kwargs):
160
"""
161
Retrieve a property_item object for a given page_id and property_id.
162
163
Parameters:
164
- page_id: str, page ID
165
- property_id: str, property ID
166
- start_cursor: str, pagination cursor for property values
167
- page_size: int, number of results per page
168
- auth: str, optional auth token for this request
169
170
Returns:
171
Property item object dict
172
"""
173
```
174
175
### Block Operations
176
177
Interface for working with Notion blocks including retrieval, updates, deletion, and managing block children.
178
179
```python { .api }
180
class BlocksEndpoint:
181
"""Block operations endpoint."""
182
183
# Sub-endpoint for block children
184
children: BlocksChildrenEndpoint
185
186
def retrieve(self, block_id, **kwargs):
187
"""
188
Retrieve a Block object using the ID specified.
189
190
Parameters:
191
- block_id: str, block ID
192
- auth: str, optional auth token for this request
193
194
Returns:
195
Block object dict
196
"""
197
198
def update(self, block_id, **kwargs):
199
"""
200
Update the content for the specified block_id based on the block type.
201
202
Parameters:
203
- block_id: str, block ID
204
- type: str, block type
205
- archived: bool, whether to archive the block
206
- in_trash: bool, whether to move block to trash
207
- [block_type]: dict, block-specific content (e.g., paragraph, heading_1, etc.)
208
- auth: str, optional auth token for this request
209
210
Supported block types:
211
- paragraph, heading_1, heading_2, heading_3
212
- bulleted_list_item, numbered_list_item, to_do, toggle
213
- quote, callout, code, equation, divider
214
- bookmark, embed, image, video, file, pdf, audio
215
- table, table_row, column, table_of_contents
216
- breadcrumb, link_to_page, template, synced_block
217
218
Returns:
219
Updated block object dict
220
"""
221
222
def delete(self, block_id, **kwargs):
223
"""
224
Set a Block object, including page blocks, to archived: true.
225
226
Parameters:
227
- block_id: str, block ID
228
- auth: str, optional auth token for this request
229
230
Returns:
231
Archived block object dict
232
"""
233
234
class BlocksChildrenEndpoint:
235
"""Block children operations endpoint."""
236
237
def list(self, block_id, **kwargs):
238
"""
239
Return a paginated array of child block objects contained in the block.
240
241
Parameters:
242
- block_id: str, parent block ID
243
- start_cursor: str, pagination cursor
244
- page_size: int, number of results per page
245
- auth: str, optional auth token for this request
246
247
Returns:
248
Dict with 'results' list of child block objects and pagination info
249
"""
250
251
def append(self, block_id, **kwargs):
252
"""
253
Create and append new children blocks to the block using the ID specified.
254
255
Parameters:
256
- block_id: str, parent block ID
257
- children: list, array of block objects to append
258
- after: str, block ID to insert children after
259
- auth: str, optional auth token for this request
260
261
Returns:
262
Dict with 'results' list of created block objects
263
"""
264
```
265
266
### User Operations
267
268
Interface for retrieving user information and workspace user lists.
269
270
```python { .api }
271
class UsersEndpoint:
272
"""User operations endpoint."""
273
274
def list(self, **kwargs):
275
"""
276
Return a paginated list of Users for the workspace.
277
278
Parameters:
279
- start_cursor: str, pagination cursor
280
- page_size: int, number of results per page
281
- auth: str, optional auth token for this request
282
283
Returns:
284
Dict with 'results' list of user objects and pagination info
285
"""
286
287
def retrieve(self, user_id, **kwargs):
288
"""
289
Retrieve a User using the ID specified.
290
291
Parameters:
292
- user_id: str, user ID
293
- auth: str, optional auth token for this request
294
295
Returns:
296
User object dict
297
"""
298
299
def me(self, **kwargs):
300
"""
301
Retrieve the bot User associated with the API token.
302
303
Parameters:
304
- auth: str, optional auth token for this request
305
306
Returns:
307
Bot user object dict
308
"""
309
```
310
311
### Search Operations
312
313
Interface for searching pages and databases across the workspace.
314
315
```python { .api }
316
class SearchEndpoint:
317
"""Search operations endpoint."""
318
319
def __call__(self, **kwargs):
320
"""
321
Search all pages and child pages that are shared with the integration.
322
323
Parameters:
324
- query: str, search query string
325
- sort: dict, sort configuration
326
- filter: dict, filter to limit search results
327
- start_cursor: str, pagination cursor
328
- page_size: int, number of results per page
329
- auth: str, optional auth token for this request
330
331
Returns:
332
Dict with 'results' list of matching page/database objects and pagination info
333
"""
334
```
335
336
### Comment Operations
337
338
Interface for creating and retrieving comments on pages and in discussion threads.
339
340
```python { .api }
341
class CommentsEndpoint:
342
"""Comment operations endpoint."""
343
344
def create(self, **kwargs):
345
"""
346
Create a new comment in the specified page or existing discussion thread.
347
348
Parameters:
349
- parent: dict, parent page reference
350
- discussion_id: str, discussion thread ID (for threaded comments)
351
- rich_text: list, comment content as rich text
352
- auth: str, optional auth token for this request
353
354
Returns:
355
Created comment object dict
356
"""
357
358
def list(self, **kwargs):
359
"""
360
Retrieve a list of un-resolved Comment objects from the specified block.
361
362
Parameters:
363
- block_id: str, block ID to get comments for
364
- start_cursor: str, pagination cursor
365
- page_size: int, number of results per page
366
- auth: str, optional auth token for this request
367
368
Returns:
369
Dict with 'results' list of comment objects and pagination info
370
"""
371
```
372
373
### File Upload Operations
374
375
Interface for uploading files to Notion including creation, completion, and management of file uploads.
376
377
```python { .api }
378
class FileUploadsEndpoint:
379
"""File upload operations endpoint."""
380
381
def create(self, **kwargs):
382
"""
383
Create a file upload.
384
385
Parameters:
386
- mode: str, upload mode ("single" or "multipart")
387
- filename: str, name of the file
388
- content_type: str, MIME type of the file
389
- number_of_parts: int, number of parts for multipart upload
390
- external_url: str, external URL for file (alternative to upload)
391
- auth: str, optional auth token for this request
392
393
Returns:
394
File upload object dict with upload URLs and metadata
395
"""
396
397
def complete(self, file_upload_id, **kwargs):
398
"""
399
Complete the file upload process.
400
401
Parameters:
402
- file_upload_id: str, file upload ID
403
- auth: str, optional auth token for this request
404
405
Returns:
406
Completed file upload object dict
407
"""
408
409
def retrieve(self, file_upload_id, **kwargs):
410
"""
411
Retrieve a file upload object using the ID specified.
412
413
Parameters:
414
- file_upload_id: str, file upload ID
415
- auth: str, optional auth token for this request
416
417
Returns:
418
File upload object dict
419
"""
420
421
def list(self, **kwargs):
422
"""
423
List all file uploads.
424
425
Parameters:
426
- status: str, filter by upload status
427
- start_cursor: str, pagination cursor
428
- page_size: int, number of results per page
429
- auth: str, optional auth token for this request
430
431
Returns:
432
Dict with 'results' list of file upload objects and pagination info
433
"""
434
435
def send(self, file_upload_id, **kwargs):
436
"""
437
Send a file upload.
438
439
Parameters:
440
- file_upload_id: str, file upload ID
441
- file: file-like object or tuple, file data to upload
442
- part_number: int, part number for multipart uploads
443
- auth: str, optional auth token for this request
444
445
Returns:
446
Upload response dict
447
"""
448
```
449
450
## Usage Examples
451
452
### Database Operations
453
454
```python
455
# Query database with filters
456
results = notion.databases.query(
457
database_id="database_id_here",
458
filter={
459
"and": [
460
{
461
"property": "Status",
462
"select": {"equals": "In Progress"}
463
},
464
{
465
"property": "Priority",
466
"number": {"greater_than": 1}
467
}
468
]
469
},
470
sorts=[
471
{
472
"property": "Created",
473
"direction": "descending"
474
}
475
]
476
)
477
478
# Create a new database
479
new_db = notion.databases.create(
480
parent={"page_id": "parent_page_id"},
481
title=[{"text": {"content": "Project Tasks"}}],
482
properties={
483
"Name": {"title": {}},
484
"Status": {
485
"select": {
486
"options": [
487
{"name": "Not Started", "color": "red"},
488
{"name": "In Progress", "color": "yellow"},
489
{"name": "Complete", "color": "green"}
490
]
491
}
492
},
493
"Priority": {"number": {}}
494
}
495
)
496
```
497
498
### Page Operations
499
500
```python
501
# Create a new page in a database
502
page = notion.pages.create(
503
parent={"database_id": "database_id_here"},
504
properties={
505
"Name": {
506
"title": [{"text": {"content": "New Task"}}]
507
},
508
"Status": {
509
"select": {"name": "In Progress"}
510
},
511
"Priority": {
512
"number": 2
513
}
514
},
515
children=[
516
{
517
"object": "block",
518
"type": "paragraph",
519
"paragraph": {
520
"rich_text": [{"text": {"content": "Task description here."}}]
521
}
522
}
523
]
524
)
525
526
# Update page properties
527
updated_page = notion.pages.update(
528
page_id="page_id_here",
529
properties={
530
"Status": {
531
"select": {"name": "Complete"}
532
}
533
}
534
)
535
```
536
537
### Block Operations
538
539
```python
540
# Get block children
541
children = notion.blocks.children.list(block_id="block_id_here")
542
543
# Append new blocks
544
notion.blocks.children.append(
545
block_id="parent_block_id",
546
children=[
547
{
548
"object": "block",
549
"type": "heading_2",
550
"heading_2": {
551
"rich_text": [{"text": {"content": "New Section"}}]
552
}
553
},
554
{
555
"object": "block",
556
"type": "paragraph",
557
"paragraph": {
558
"rich_text": [{"text": {"content": "Some content."}}]
559
}
560
}
561
]
562
)
563
564
# Update a block
565
updated_block = notion.blocks.update(
566
block_id="block_id_here",
567
paragraph={
568
"rich_text": [{"text": {"content": "Updated content."}}]
569
}
570
)
571
```
572
573
### Search Operations
574
575
```python
576
# Search for pages containing specific text
577
search_results = notion.search(
578
query="project planning",
579
filter={
580
"value": "page",
581
"property": "object"
582
},
583
sort={
584
"direction": "descending",
585
"timestamp": "last_edited_time"
586
}
587
)
588
589
# Search within specific parent
590
search_results = notion.search(
591
query="meeting notes",
592
filter={
593
"value": "page",
594
"property": "object"
595
}
596
)
597
```
598
599
### File Upload Operations
600
601
```python
602
# Create a file upload
603
with open("document.pdf", "rb") as file:
604
upload = notion.file_uploads.create(
605
mode="single",
606
filename="document.pdf",
607
content_type="application/pdf"
608
)
609
610
# Send the file data
611
notion.file_uploads.send(
612
file_upload_id=upload["id"],
613
file=file
614
)
615
616
# Complete the upload
617
completed = notion.file_uploads.complete(
618
file_upload_id=upload["id"]
619
)
620
```