0
# Notion Client
1

2
Notion Client is a robust TypeScript client for the unofficial Notion API, enabling developers to programmatically access and interact with Notion pages, databases, and collections. It supports server-side environments like Node.js, Deno, and Cloudflare Workers, offering comprehensive functionality for fetching page content, database queries, collection views, and handling authentication for private Notion resources.
3

4
## Package Information
5

6
- **Package Name**: notion-client
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install notion-client`
10

11
## Core Imports
12

13
```typescript
14
import { NotionAPI } from "notion-client";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { NotionAPI } = require("notion-client");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { NotionAPI } from "notion-client";
27

28
// Create API client (public access)
29
const api = new NotionAPI();
30

31
// Create API client with authentication
32
const authenticatedApi = new NotionAPI({
33
  authToken: "your-token-here",
34
  activeUser: "user-id"
35
});
36

37
// Fetch a complete page with all blocks and collections
38
const page = await api.getPage("067dd719-a912-471e-a9a3-ac10710e7fdf");
39

40
// Fetch raw page data
41
const rawPage = await api.getPageRaw("067dd719-a912-471e-a9a3-ac10710e7fdf");
42

43
// Search within a workspace
44
const searchResults = await api.search({
45
  ancestorId: "workspace-id",
46
  query: "search term",
47
  limit: 20
48
});
49
```
50

51
## Architecture
52

53
Notion Client is designed around several key components:
54

55
- **NotionAPI Class**: Primary interface providing all API methods with optional authentication
56
- **Page Operations**: Complete page fetching with automatic block resolution and collection data loading
57
- **Collection System**: Database and collection view queries with filtering and sorting support
58
- **Search Engine**: Full-text search across Notion workspaces with filtering options
59
- **File Management**: Signed URL generation for secure file access
60
- **Type Safety**: Full TypeScript integration with comprehensive type definitions from notion-types
61

62
## Capabilities
63

64
### Core API Operations
65

66
Primary NotionAPI class providing page fetching, authentication, and low-level API access. Essential for all Notion interactions.
67

68
```typescript { .api }
69
class NotionAPI {
70
  constructor(options?: NotionAPIOptions);
71
  getPage(pageId: string, options?: GetPageOptions): Promise<ExtendedRecordMap>;
72
  getPageRaw(pageId: string, options?: GetPageRawOptions): Promise<PageChunk>;
73
  fetch<T>(options: FetchOptions): Promise<T>;
74
}
75

76
interface NotionAPIOptions {
77
  apiBaseUrl?: string;
78
  authToken?: string;
79
  activeUser?: string;
80
  userTimeZone?: string;
81
  kyOptions?: KyOptions;
82
}
83
```
84

85
[Core API Operations](./core-api.md)
86

87
### Collection Operations
88

89
Database and collection view management for querying structured data, including filtering, sorting, and pagination. Perfect for working with Notion databases.
90

91
```typescript { .api }
92
getCollectionData(
93
  collectionId: string,
94
  collectionViewId: string,
95
  collectionView: any,
96
  options?: GetCollectionDataOptions
97
): Promise<CollectionInstance>;
98

99
interface GetCollectionDataOptions {
100
  type?: CollectionViewType;
101
  limit?: number;
102
  searchQuery?: string;
103
  userTimeZone?: string;
104
  loadContentCover?: boolean;
105
  kyOptions?: KyOptions;
106
}
107
```
108

109
[Collection Operations](./collections.md)
110

111
### Search Operations
112

113
Full-text search capabilities across Notion workspaces with advanced filtering and result ranking.
114

115
```typescript { .api }
116
search(params: SearchParams, kyOptions?: KyOptions): Promise<SearchResults>;
117

118
interface SearchParams {
119
  ancestorId: string;
120
  query: string;
121
  limit?: number;
122
  filters?: SearchFilters;
123
}
124
```
125

126
[Search Operations](./search.md)
127

128
### Block and User Operations
129

130
Low-level operations for fetching individual blocks and user information, useful for granular data access.
131

132
```typescript { .api }
133
getBlocks(blockIds: string[], kyOptions?: KyOptions): Promise<PageChunk>;
134
getUsers(userIds: string[], kyOptions?: KyOptions): Promise<RecordValues<User>>;
135
```
136

137
[Block and User Operations](./blocks-users.md)
138

139
### File and URL Operations
140

141
Secure file access through signed URLs and file URL management for media and document handling.
142

143
```typescript { .api }
144
getSignedFileUrls(
145
  urls: SignedUrlRequest[],
146
  kyOptions?: KyOptions
147
): Promise<SignedUrlResponse>;
148

149
addSignedUrls(options: AddSignedUrlsOptions): Promise<void>;
150

151
interface SignedUrlRequest {
152
  permissionRecord: PermissionRecord;
153
  url: string;
154
}
155

156
interface SignedUrlResponse {
157
  signedUrls: string[];
158
}
159
```
160

161
[File and URL Operations](./files-urls.md)
162

163
## Types
164

165
```typescript { .api }
166
interface PermissionRecord {
167
  table: string;
168
  id: string;
169
}
170

171
interface GetPageOptions {
172
  concurrency?: number;
173
  fetchMissingBlocks?: boolean;
174
  fetchCollections?: boolean;
175
  signFileUrls?: boolean;
176
  chunkLimit?: number;
177
  chunkNumber?: number;
178
  throwOnCollectionErrors?: boolean;
179
  collectionReducerLimit?: number;
180
  fetchRelationPages?: boolean;
181
  kyOptions?: KyOptions;
182
}
183

184
interface GetPageRawOptions {
185
  chunkLimit?: number;
186
  chunkNumber?: number;
187
  kyOptions?: KyOptions;
188
}
189

190
interface AddSignedUrlsOptions {
191
  recordMap: ExtendedRecordMap;
192
  contentBlockIds?: string[];
193
  kyOptions?: KyOptions;
194
}
195

196
interface FetchOptions {
197
  endpoint: string;
198
  body: object;
199
  kyOptions?: KyOptions;
200
  headers?: any;
201
}
202
```