0
# Notion SDK for JavaScript
1

2
The Notion SDK for JavaScript is a simple and easy to use client for the Notion API. It provides a comprehensive TypeScript/JavaScript SDK that enables developers to integrate with Notion workspaces programmatically, offering a complete client library with strongly-typed interfaces for all Notion API endpoints.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { Client } from "@notionhq/client";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { Client } = require("@notionhq/client");
21
```
22

23
Additional imports for types and utilities:
24

25
```typescript
26
import { 
27
  Client, 
28
  APIErrorCode, 
29
  LogLevel, 
30
  isNotionClientError,
31
  collectPaginatedAPI,
32
  iteratePaginatedAPI,
33
  isFullPage,
34
  isFullBlock,
35
  isFullUser,
36
  isFullComment,
37
  isFullDatabase,
38
  isFullDataSource,
39
  isFullPageOrDataSource,
40
  isTextRichTextItemResponse,
41
  isEquationRichTextItemResponse,
42
  isMentionRichTextItemResponse
43
} from "@notionhq/client";
44
```
45

46
## Basic Usage
47

48
```typescript
49
import { Client } from "@notionhq/client";
50

51
// Initialize client with authentication
52
const notion = new Client({
53
  auth: process.env.NOTION_TOKEN,
54
});
55

56
// List users in workspace
57
const users = await notion.users.list({});
58

59
// Create a new page
60
const page = await notion.pages.create({
61
  parent: { database_id: "your-database-id" },
62
  properties: {
63
    title: {
64
      title: [{ text: { content: "New Page" } }],
65
    },
66
  },
67
});
68

69
// Query a database
70
const database = await notion.databases.retrieve({
71
  database_id: "your-database-id",
72
});
73
```
74

75
## Architecture
76

77
The Notion SDK is built around several key components:
78

79
- **Client Class**: Main entry point providing organized endpoint namespaces (blocks, pages, databases, users, etc.)
80
- **Type System**: Comprehensive TypeScript definitions for all API objects and operations (150+ types)
81
- **Error Handling**: Specialized error classes with specific error codes for API and client errors
82
- **Pagination Helpers**: Utilities for handling paginated API responses
83
- **Logging System**: Configurable logging with multiple severity levels
84
- **OAuth Support**: Complete OAuth flow implementation for app integrations
85

86
## Capabilities
87

88
### Client Configuration
89

90
Client initialization and configuration options for authentication, timeouts, logging, and API versioning.
91

92
```typescript { .api }
93
class Client {
94
  constructor(options?: ClientOptions);
95
}
96

97
interface ClientOptions {
98
  auth?: string;
99
  timeoutMs?: number;
100
  baseUrl?: string;
101
  logLevel?: LogLevel;
102
  logger?: Logger;
103
  notionVersion?: string;
104
  fetch?: SupportedFetch;
105
  agent?: Agent;
106
}
107
```
108

109
[Client Configuration](./client-configuration.md)
110

111
### Page Operations
112

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

115
```typescript { .api }
116
pages: {
117
  create(args: CreatePageParameters): Promise<CreatePageResponse>;
118
  retrieve(args: GetPageParameters): Promise<GetPageResponse>;
119
  update(args: UpdatePageParameters): Promise<UpdatePageResponse>;
120
  properties: {
121
    retrieve(args: GetPagePropertyParameters): Promise<GetPagePropertyResponse>;
122
  };
123
}
124
```
125

126
[Page Operations](./page-operations.md)
127

128
### Database Operations
129

130
Manage Notion databases including creation, updates, and retrieval of database schemas and metadata.
131

132
```typescript { .api }
133
databases: {
134
  retrieve(args: GetDatabaseParameters): Promise<GetDatabaseResponse>;
135
  create(args: CreateDatabaseParameters): Promise<CreateDatabaseResponse>;
136
  update(args: UpdateDatabaseParameters): Promise<UpdateDatabaseResponse>;
137
}
138
```
139

140
[Database Operations](./database-operations.md)
141

142
### Data Source Operations
143

144
Query and manage data sources (database content) with filtering, sorting, and pagination capabilities.
145

146
```typescript { .api }
147
dataSources: {
148
  retrieve(args: GetDataSourceParameters): Promise<GetDataSourceResponse>;
149
  create(args: CreateDataSourceParameters): Promise<CreateDataSourceResponse>;
150
  update(args: UpdateDataSourceParameters): Promise<UpdateDataSourceResponse>;
151
  query(args: QueryDataSourceParameters): Promise<QueryDataSourceResponse>;
152
}
153
```
154

155
[Data Source Operations](./data-source-operations.md)
156

157
### Block Operations
158

159
Manipulate page content through blocks - the building blocks of Notion pages including text, images, lists, and more.
160

161
```typescript { .api }
162
blocks: {
163
  retrieve(args: GetBlockParameters): Promise<GetBlockResponse>;
164
  update(args: UpdateBlockParameters): Promise<UpdateBlockResponse>;
165
  delete(args: DeleteBlockParameters): Promise<DeleteBlockResponse>;
166
  children: {
167
    append(args: AppendBlockChildrenParameters): Promise<AppendBlockChildrenResponse>;
168
    list(args: ListBlockChildrenParameters): Promise<ListBlockChildrenResponse>;
169
  };
170
}
171
```
172

173
[Block Operations](./block-operations.md)
174

175
### User Management
176

177
Retrieve information about users in the Notion workspace including the current authenticated user.
178

179
```typescript { .api }
180
users: {
181
  retrieve(args: GetUserParameters): Promise<GetUserResponse>;
182
  list(args: ListUsersParameters): Promise<ListUsersResponse>;
183
  me(args: GetSelfParameters): Promise<GetSelfResponse>;
184
}
185
```
186

187
[User Management](./user-management.md)
188

189
### Comments
190

191
Create and manage comments on pages and blocks for collaboration features.
192

193
```typescript { .api }
194
comments: {
195
  create(args: CreateCommentParameters): Promise<CreateCommentResponse>;
196
  list(args: ListCommentsParameters): Promise<ListCommentsResponse>;
197
  retrieve(args: GetCommentParameters): Promise<GetCommentResponse>;
198
}
199
```
200

201
[Comments](./comments.md)
202

203
### File Uploads
204

205
Handle file uploads to Notion including creation, sending, and completion of upload processes.
206

207
```typescript { .api }
208
fileUploads: {
209
  create(args: CreateFileUploadParameters): Promise<CreateFileUploadResponse>;
210
  retrieve(args: GetFileUploadParameters): Promise<GetFileUploadResponse>;
211
  send(args: SendFileUploadParameters): Promise<SendFileUploadResponse>;
212
  complete(args: CompleteFileUploadParameters): Promise<CompleteFileUploadResponse>;
213
  list(args: ListFileUploadsParameters): Promise<ListFileUploadsResponse>;
214
}
215
```
216

217
[File Uploads](./file-uploads.md)
218

219
### Search
220

221
Search across the entire Notion workspace for pages, databases, and other content.
222

223
```typescript { .api }
224
search(args: SearchParameters): Promise<SearchResponse>;
225
```
226

227
[Search](./search.md)
228

229
### OAuth Authentication
230

231
Complete OAuth flow implementation for Notion app integrations including token exchange and management.
232

233
```typescript { .api }
234
oauth: {
235
  token(args: OauthTokenParameters): Promise<OauthTokenResponse>;
236
  revoke(args: OauthRevokeParameters): Promise<OauthRevokeResponse>;
237
  introspect(args: OauthIntrospectParameters): Promise<OauthIntrospectResponse>;
238
}
239
```
240

241
[OAuth Authentication](./oauth-authentication.md)
242

243
### Error Handling
244

245
Comprehensive error handling with specific error types and codes for different failure scenarios.
246

247
```typescript { .api }
248
enum APIErrorCode {
249
  Unauthorized = "unauthorized";
250
  RestrictedResource = "restricted_resource";
251
  ObjectNotFound = "object_not_found";
252
  RateLimited = "rate_limited";
253
  InvalidJSON = "invalid_json";
254
  InvalidRequestURL = "invalid_request_url";
255
  InvalidRequest = "invalid_request";
256
  ValidationError = "validation_error";
257
  ConflictError = "conflict_error";
258
  InternalServerError = "internal_server_error";
259
  ServiceUnavailable = "service_unavailable";
260
}
261

262
function isNotionClientError(error: unknown): error is NotionClientError;
263
```
264

265
[Error Handling](./error-handling.md)
266

267
### Pagination Helpers
268

269
Utility functions for handling paginated API responses with automatic cursor management.
270

271
```typescript { .api }
272
function iteratePaginatedAPI<T>(
273
  listFn: Function,
274
  args: any
275
): AsyncIterableIterator<T>;
276

277
function collectPaginatedAPI<T>(
278
  listFn: Function,
279
  args: any
280
): Promise<T[]>;
281
```
282

283
[Pagination Helpers](./pagination-helpers.md)
284

285
## Types
286

287
Core shared types used across multiple capabilities:
288

289
```typescript { .api }
290
enum LogLevel {
291
  DEBUG = "debug";
292
  INFO = "info"; 
293
  WARN = "warn";
294
  ERROR = "error";
295
}
296

297
interface Logger {
298
  (level: LogLevel, message: string, extraInfo: Record<string, unknown>): void;
299
}
300

301
type UserObjectResponse = PersonUserObjectResponse | BotUserObjectResponse;
302
type RichTextItemResponse = TextRichTextItemResponse | MentionRichTextItemResponse | EquationRichTextItemResponse;
303
type BlockObjectResponse = ParagraphBlockObjectResponse | Heading1BlockObjectResponse | /* ... all block types ... */;
304
```