0
# API Types
1

2
Type definitions for Notion API requests, responses, search operations, and aggregate data structures including RecordMaps and ExtendedRecordMaps.
3

4
## Capabilities
5

6
### Record Maps
7

8
Core data structures for Notion API responses that aggregate related data with permission information.
9

10
```typescript { .api }
11
/**
12
 * Generic wrapper for Notion data with role permissions
13
 */
14
interface NotionMap<T> {
15
  [key: string]: {
16
    /** User's role/permission for this item */
17
    role: Role;
18
    /** The actual data item */
19
    value: T;
20
  };
21
}
22

23
/**
24
 * Specific map types for different data categories
25
 */
26
type BlockMap = NotionMap<Block>;
27
type UserMap = NotionMap<User>;
28
type CollectionMap = NotionMap<Collection>;
29
type CollectionViewMap = NotionMap<CollectionView>;
30

31
/**
32
 * Map of property values
33
 */
34
interface PropertyMap {
35
  [key: string]: Decoration[];
36
}
37

38
/**
39
 * Core data structure for Notion API responses
40
 */
41
interface RecordMap {
42
  /** Block data (required) */
43
  block: BlockMap;
44
  /** Collection data (optional) */
45
  collection?: CollectionMap;
46
  /** Collection view data (optional) */
47
  collection_view?: CollectionViewMap;
48
  /** User data (optional) */
49
  notion_user?: UserMap;
50
}
51

52
/**
53
 * Enhanced record map with convenience data
54
 */
55
interface ExtendedRecordMap extends RecordMap {
56
  /** Collection data (required) */
57
  collection: CollectionMap;
58
  /** Collection view data (required) */
59
  collection_view: CollectionViewMap;
60
  /** User data (required) */
61
  notion_user: UserMap;
62
  /** Collection query results */
63
  collection_query: {
64
    [collectionId: string]: {
65
      [collectionViewId: string]: CollectionQueryResult;
66
    };
67
  };
68
  /** Signed URLs for file access */
69
  signed_urls: {
70
    [blockId: string]: string;
71
  };
72
  /** Optional preview images */
73
  preview_images?: PreviewImageMap;
74
}
75
```
76

77
### API Request Types
78

79
```typescript { .api }
80
/**
81
 * Generic interface for API result sets
82
 */
83
interface RecordValues<T> {
84
  /** Array of result items */
85
  results: T[];
86
}
87

88
/**
89
 * Parameters for search operations
90
 */
91
interface SearchParams {
92
  /** ID of ancestor block to search within */
93
  ancestorId: string;
94
  /** Search query string */
95
  query: string;
96
  /** Optional search filters */
97
  filters?: {
98
    isDeletedOnly: boolean;
99
    excludeTemplates: boolean;
100
    isNavigableOnly: boolean;
101
    requireEditPermissions: boolean;
102
  };
103
  /** Optional result limit */
104
  limit?: number;
105
  /** Optional session ID */
106
  searchSessionId?: string;
107
}
108
```
109

110
### API Response Types
111

112
```typescript { .api }
113
/**
114
 * Search operation results
115
 */
116
interface SearchResults {
117
  /** Map of retrieved records */
118
  recordMap: RecordMap;
119
  /** Array of search result items */
120
  results: SearchResult[];
121
  /** Total number of results */
122
  total: number;
123
}
124

125
/**
126
 * Individual search result item
127
 */
128
interface SearchResult {
129
  /** Result item ID */
130
  id: string;
131
  /** Whether item can be navigated to */
132
  isNavigable: boolean;
133
  /** Search relevance score */
134
  score: number;
135
  /** Highlighted text snippets */
136
  highlight: {
137
    pathText: string;
138
    text: string;
139
  };
140
}
141

142
/**
143
 * API error response structure
144
 */
145
interface APIError {
146
  /** Unique error identifier */
147
  errorId: string;
148
  /** Error name/type */
149
  name: string;
150
  /** Human-readable error message */
151
  message: string;
152
}
153
```
154

155
### Collection Query Results
156

157
```typescript { .api }
158
/**
159
 * Page data chunk from API
160
 */
161
interface PageChunk {
162
  /** Page record data */
163
  recordMap: RecordMap;
164
  /** Pagination cursor */
165
  cursor: {
166
    stack: any[];
167
  };
168
}
169

170
/**
171
 * Collection data with query results
172
 */
173
interface CollectionInstance {
174
  /** Collection record data */
175
  recordMap: RecordMap;
176
  /** Query execution results */
177
  result: CollectionQueryResult;
178
}
179

180
/**
181
 * Results from collection query
182
 */
183
interface CollectionQueryResult {
184
  /** View type that generated results */
185
  type: CollectionViewType;
186
  /** Total number of results */
187
  total: number;
188
  /** Array of result block IDs */
189
  blockIds: string[];
190
  /** Aggregation computation results */
191
  aggregationResults: Array<AggregationResult>;
192
  /** Board view grouping results (optional) */
193
  groupResults?: Array<{
194
    value: AggregationResult;
195
    blockIds: string[];
196
    total: number;
197
    aggregationResult: AggregationResult;
198
  }>;
199
  /** Collection grouping results (optional) */
200
  collection_group_results?: {
201
    type: string;
202
    blockIds: string[];
203
    hasMore: boolean;
204
  };
205
  /** Reducer view results (optional) */
206
  reducerResults?: {
207
    collection_group_results: {
208
      type: string;
209
      blockIds: string[];
210
      hasMore: boolean;
211
    };
212
  };
213
  /** Associated collection IDs (optional) */
214
  collectionIds?: string[];
215
  /** Embedded record map (optional) */
216
  recordMap?: ExtendedRecordMap;
217
}
218

219
/**
220
 * Result of aggregation function
221
 */
222
interface AggregationResult {
223
  /** Property type being aggregated */
224
  type: PropertyType;
225
  /** Aggregated value */
226
  value: any;
227
}
228
```
229

230
### Utility Types
231

232
```typescript { .api }
233
/**
234
 * Map of page data
235
 */
236
interface PageMap {
237
  [pageId: string]: ExtendedRecordMap | null;
238
}
239

240
/**
241
 * Preview image metadata
242
 */
243
interface PreviewImage {
244
  /** Original image width */
245
  originalWidth: number;
246
  /** Original image height */
247
  originalHeight: number;
248
  /** Base64 data URI of preview */
249
  dataURIBase64: string;
250
}
251

252
/**
253
 * Map of preview images
254
 */
255
interface PreviewImageMap {
256
  [url: string]: PreviewImage | null;
257
}
258
```
259

260
**Usage Examples:**
261

262
```typescript
263
import { 
264
  RecordMap,
265
  ExtendedRecordMap,
266
  SearchParams,
267
  SearchResults,
268
  CollectionQueryResult,
269
  PageChunk,
270
  NotionMap 
271
} from "notion-types";
272

273
// Create search parameters
274
const searchParams: SearchParams = {
275
  ancestorId: "page-123",
276
  query: "project management",
277
  filters: {
278
    isDeletedOnly: false,
279
    excludeTemplates: true,
280
    isNavigableOnly: true,
281
    requireEditPermissions: false
282
  },
283
  limit: 20
284
};
285

286
// Process search results
287
function processSearchResults(results: SearchResults) {
288
  console.log(`Found ${results.total} results`);
289
  
290
  results.results.forEach(result => {
291
    console.log(`${result.id}: ${result.highlight.text} (score: ${result.score})`);
292
  });
293
  
294
  // Access the record map
295
  const blocks = Object.keys(results.recordMap.block);
296
  console.log(`Retrieved ${blocks.length} blocks`);
297
}
298

299
// Work with RecordMap
300
function processRecordMap(recordMap: RecordMap) {
301
  // Process blocks
302
  Object.entries(recordMap.block).forEach(([blockId, blockData]) => {
303
    console.log(`Block ${blockId} (role: ${blockData.role})`);
304
    console.log(`Type: ${blockData.value.type}`);
305
  });
306
  
307
  // Process collections if present
308
  if (recordMap.collection) {
309
    Object.entries(recordMap.collection).forEach(([collectionId, collectionData]) => {
310
      console.log(`Collection ${collectionId}: ${collectionData.value.name}`);
311
    });
312
  }
313
  
314
  // Process users if present
315
  if (recordMap.notion_user) {
316
    Object.entries(recordMap.notion_user).forEach(([userId, userData]) => {
317
      console.log(`User ${userId}: ${userData.value.given_name} ${userData.value.family_name}`);
318
    });
319
  }
320
}
321

322
// Create an extended record map
323
const extendedRecordMap: ExtendedRecordMap = {
324
  block: {},
325
  collection: {},
326
  collection_view: {},
327
  notion_user: {},
328
  collection_query: {
329
    "collection-123": {
330
      "view-456": {
331
        type: "table",
332
        total: 10,
333
        blockIds: ["block-1", "block-2", "block-3"],
334
        aggregationResults: []
335
      }
336
    }
337
  },
338
  signed_urls: {
339
    "image-block-789": "https://signed-url.example.com/image.png"
340
  }
341
};
342

343
// Process collection query results
344
function processCollectionQuery(result: CollectionQueryResult) {
345
  console.log(`Query returned ${result.total} items of type ${result.type}`);
346
  
347
  result.blockIds.forEach(blockId => {
348
    console.log(`Result block: ${blockId}`);
349
  });
350
  
351
  if (result.groupResults) {
352
    result.groupResults.forEach(group => {
353
      console.log(`Group has ${group.blockIds.length} items`);
354
    });
355
  }
356
}
357

358
// Handle API errors
359
function handleAPIError(error: APIError) {
360
  console.error(`API Error [${error.errorId}]: ${error.name}`);
361
  console.error(`Message: ${error.message}`);
362
}
363

364
// Type-safe access to NotionMap
365
function getBlockFromMap(blockMap: BlockMap, blockId: string): Block | null {
366
  const blockData = blockMap[blockId];
367
  return blockData ? blockData.value : null;
368
}
369

370
// Check user permissions
371
function hasEditPermission(blockMap: BlockMap, blockId: string): boolean {
372
  const blockData = blockMap[blockId];
373
  return blockData ? blockData.role === 'editor' : false;
374
}
375
```