0
# Client Configuration
1

2
Client initialization and configuration options for authentication, timeouts, logging, and API versioning.
3

4
## Capabilities
5

6
### Client Constructor
7

8
Initialize a new Notion client with optional configuration options.
9

10
```typescript { .api }
11
/**
12
 * Creates a new Notion client instance
13
 * @param options - Optional configuration options
14
 */
15
class Client {
16
  constructor(options?: ClientOptions);
17
}
18

19
interface ClientOptions {
20
  /** API token or OAuth access token for authentication */
21
  auth?: string;
22
  /** Request timeout in milliseconds (default: 60000) */
23
  timeoutMs?: number;
24
  /** Base API URL (default: "https://api.notion.com") */
25
  baseUrl?: string;
26
  /** Logging level (default: LogLevel.WARN) */
27
  logLevel?: LogLevel;
28
  /** Custom logger function */
29
  logger?: Logger;
30
  /** Notion API version (default: "2025-09-03") */
31
  notionVersion?: string;
32
  /** Custom fetch implementation */
33
  fetch?: SupportedFetch;
34
  /** HTTP agent for Node.js (ignored in browser) */
35
  agent?: Agent;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { Client, LogLevel } from "@notionhq/client";
43

44
// Basic initialization with token
45
const notion = new Client({
46
  auth: process.env.NOTION_TOKEN,
47
});
48

49
// Advanced configuration
50
const notion = new Client({
51
  auth: process.env.NOTION_TOKEN,
52
  timeoutMs: 30000,
53
  logLevel: LogLevel.DEBUG,
54
  notionVersion: "2025-09-03",
55
});
56

57
// OAuth initialization
58
const notion = new Client({
59
  auth: oauthAccessToken,
60
  logLevel: LogLevel.INFO,
61
});
62
```
63

64
### Generic Request Method
65

66
Low-level request method for making custom API calls.
67

68
```typescript { .api }
69
/**
70
 * Sends a request to the Notion API
71
 * @param args - Request parameters including path, method, query, body
72
 * @returns Promise resolving to the response body
73
 */
74
request<ResponseBody>(args: RequestParameters): Promise<ResponseBody>;
75

76
interface RequestParameters {
77
  /** API endpoint path */
78
  path: string;
79
  /** HTTP method */
80
  method: "get" | "post" | "patch" | "delete";
81
  /** Query parameters */
82
  query?: Record<string, string | number | string[]> | URLSearchParams;
83
  /** Request body */
84
  body?: Record<string, unknown>;
85
  /** Form data parameters for file uploads */
86
  formDataParams?: Record<string, string | FileParam>;
87
  /** Additional headers */
88
  headers?: Record<string, string>;
89
  /** Override authentication for this request */
90
  auth?: string | {
91
    client_id: string;
92
    client_secret: string;
93
  };
94
}
95

96
type FileParam = {
97
  filename?: string;
98
  data: string | Blob;
99
};
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
// Custom API request
106
const response = await notion.request({
107
  path: "pages/abc123",
108
  method: "get",
109
  query: { filter_properties: ["title"] },
110
});
111

112
// Request with custom auth
113
const response = await notion.request({
114
  path: "users/me",
115
  method: "get",
116
  auth: customToken,
117
});
118
```
119

120
### Static Properties
121

122
```typescript { .api }
123
/**
124
 * Default Notion API version used by the client
125
 */
126
static readonly defaultNotionVersion: string;
127
```
128

129
## Types
130

131
```typescript { .api }
132
enum LogLevel {
133
  DEBUG = "debug";
134
  INFO = "info";
135
  WARN = "warn";
136
  ERROR = "error";
137
}
138

139
interface Logger {
140
  (level: LogLevel, message: string, extraInfo: Record<string, unknown>): void;
141
}
142

143
type SupportedFetch = typeof fetch;
144

145
interface Agent {
146
  // Node.js HTTP agent interface
147
}
148
```