0
# Core API Operations
1

2
Core NotionAPI class providing page fetching, authentication, and low-level API access. Essential for all Notion interactions.
3

4
## Capabilities
5

6
### NotionAPI Constructor
7

8
Creates a new Notion API client instance with optional authentication and configuration.
9

10
```typescript { .api }
11
/**
12
 * Creates a new Notion API client instance
13
 * @param options - Configuration options for the API client
14
 */
15
constructor(options?: NotionAPIOptions);
16

17
interface NotionAPIOptions {
18
  /** Base URL for Notion API (default: 'https://www.notion.so/api/v3') */
19
  apiBaseUrl?: string;
20
  /** Authentication token for private resources */
21
  authToken?: string;
22
  /** Active user ID for authenticated requests */
23
  activeUser?: string;
24
  /** User timezone (default: 'America/New_York') */
25
  userTimeZone?: string;
26
  /** Additional HTTP client options */
27
  kyOptions?: KyOptions;
28
}
29
```
30

31
**Usage Examples:**
32

33
```typescript
34
import { NotionAPI } from "notion-client";
35

36
// Basic client for public pages
37
const api = new NotionAPI();
38

39
// Authenticated client for private resources
40
const authApi = new NotionAPI({
41
  authToken: "token_v2_value_from_cookies",
42
  activeUser: "user-uuid",
43
  userTimeZone: "UTC"
44
});
45

46
// Client with custom API base URL
47
const customApi = new NotionAPI({
48
  apiBaseUrl: "https://custom-notion-proxy.com/api/v3",
49
  kyOptions: {
50
    timeout: 30000,
51
    retry: 3
52
  }
53
});
54
```
55

56
### Get Page
57

58
Fetches a complete Notion page with all blocks, collections, and signed URLs. This is the primary method for retrieving page content.
59

60
```typescript { .api }
61
/**
62
 * Fetches a complete Notion page with all content
63
 * @param pageId - The Notion page ID (with or without dashes)
64
 * @param options - Options for controlling fetch behavior
65
 * @returns Promise resolving to complete page data
66
 */
67
async getPage(pageId: string, options?: GetPageOptions): Promise<ExtendedRecordMap>;
68

69
interface GetPageOptions {
70
  /** Number of concurrent requests for fetching blocks (default: 3) */
71
  concurrency?: number;
72
  /** Fetch missing blocks automatically (default: true) */
73
  fetchMissingBlocks?: boolean;
74
  /** Fetch collection data automatically (default: true) */
75
  fetchCollections?: boolean;
76
  /** Generate signed URLs for files (default: true) */
77
  signFileUrls?: boolean;
78
  /** Number of blocks to fetch per chunk (default: 100) */
79
  chunkLimit?: number;
80
  /** Starting chunk number (default: 0) */
81
  chunkNumber?: number;
82
  /** Throw errors when collection fetching fails (default: false) */
83
  throwOnCollectionErrors?: boolean;
84
  /** Limit for collection data fetching (default: 999) */
85
  collectionReducerLimit?: number;
86
  /** Fetch pages referenced in relations (default: false) */
87
  fetchRelationPages?: boolean;
88
  /** HTTP client options for this request */
89
  kyOptions?: KyOptions;
90
}
91

92
interface ExtendedRecordMap {
93
  block: Record<string, BlockRecord>;
94
  collection: Record<string, CollectionRecord>;
95
  collection_view: Record<string, CollectionViewRecord>;
96
  notion_user: Record<string, UserRecord>;
97
  collection_query: Record<string, any>;
98
  signed_urls: Record<string, string>;
99
}
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import { NotionAPI } from "notion-client";
106

107
const api = new NotionAPI();
108

109
// Fetch a complete page with all default options
110
const page = await api.getPage("067dd719-a912-471e-a9a3-ac10710e7fdf");
111

112
// Fetch page without collections for faster loading
113
const pageNoCollections = await api.getPage("067dd719", {
114
  fetchCollections: false,
115
  signFileUrls: false
116
});
117

118
// Fetch page with relation pages and custom limits
119
const pageWithRelations = await api.getPage("067dd719", {
120
  fetchRelationPages: true,
121
  collectionReducerLimit: 50,
122
  concurrency: 5
123
});
124

125
// Access page content
126
console.log("Page blocks:", Object.keys(page.block).length);
127
console.log("Collections:", Object.keys(page.collection).length);
128
console.log("Signed URLs:", Object.keys(page.signed_urls).length);
129
```
130

131
### Get Page Raw
132

133
Fetches raw page data without additional processing like collection fetching or URL signing. Useful for performance-critical applications.
134

135
```typescript { .api }
136
/**
137
 * Fetches raw page data without additional processing
138
 * @param pageId - The Notion page ID
139
 * @param options - Options for controlling fetch behavior
140
 * @returns Promise resolving to raw page chunk data
141
 */
142
async getPageRaw(pageId: string, options?: GetPageRawOptions): Promise<PageChunk>;
143

144
interface GetPageRawOptions {
145
  /** Number of blocks to fetch per chunk (default: 100) */
146
  chunkLimit?: number;
147
  /** Starting chunk number (default: 0) */
148
  chunkNumber?: number;
149
  /** HTTP client options for this request */
150
  kyOptions?: KyOptions;
151
}
152

153
interface PageChunk {
154
  recordMap: RecordMap;
155
  cursor: Cursor;
156
}
157
```
158

159
**Usage Examples:**
160

161
```typescript
162
import { NotionAPI } from "notion-client";
163

164
const api = new NotionAPI();
165

166
// Fetch raw page data for performance
167
const rawPage = await api.getPageRaw("067dd719-a912-471e-a9a3-ac10710e7fdf");
168

169
// Fetch specific chunk of large page
170
const pageChunk = await api.getPageRaw("067dd719", {
171
  chunkLimit: 50,
172
  chunkNumber: 1
173
});
174

175
// Access raw record map
176
const blocks = rawPage.recordMap.block;
177
console.log("Raw blocks:", Object.keys(blocks).length);
178
```
179

180
### Low-Level Fetch
181

182
Direct access to Notion API endpoints for custom requests and advanced use cases.
183

184
```typescript { .api }
185
/**
186
 * Low-level fetch method for custom API requests
187
 * @param options - Request configuration
188
 * @returns Promise resolving to API response
189
 */
190
async fetch<T>(options: FetchOptions): Promise<T>;
191

192
interface FetchOptions {
193
  /** API endpoint name (e.g., 'loadPageChunk', 'queryCollection') */
194
  endpoint: string;
195
  /** Request body data */
196
  body: object;
197
  /** HTTP client options for this request */
198
  kyOptions?: KyOptions;
199
  /** Additional HTTP headers */
200
  headers?: Record<string, string>;
201
}
202
```
203

204
**Usage Examples:**
205

206
```typescript
207
import { NotionAPI } from "notion-client";
208

209
const api = new NotionAPI({ authToken: "your-token" });
210

211
// Custom API call to load page chunk
212
const customPageData = await api.fetch({
213
  endpoint: "loadPageChunk",
214
  body: {
215
    pageId: "067dd719-a912-471e-a9a3-ac10710e7fdf",
216
    limit: 50,
217
    cursor: { stack: [] },
218
    chunkNumber: 0,
219
    verticalColumns: false
220
  }
221
});
222

223
// Custom API call with additional headers
224
const customRequest = await api.fetch({
225
  endpoint: "customEndpoint",
226
  body: { data: "example" },
227
  headers: {
228
    "X-Custom-Header": "value"
229
  },
230
  kyOptions: {
231
    timeout: 15000
232
  }
233
});
234
```