or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

blocks-users.mdcollections.mdcore-api.mdfiles-urls.mdindex.mdsearch.md
tile.json

tessl/npm-notion-client

Robust TypeScript client for the unofficial Notion API.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/notion-client@7.4.x

To install, run

npx @tessl/cli install tessl/npm-notion-client@7.4.0

index.mddocs/

Notion Client

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.

Package Information

  • Package Name: notion-client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install notion-client

Core Imports

import { NotionAPI } from "notion-client";

For CommonJS:

const { NotionAPI } = require("notion-client");

Basic Usage

import { NotionAPI } from "notion-client";

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

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

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

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

// Search within a workspace
const searchResults = await api.search({
  ancestorId: "workspace-id",
  query: "search term",
  limit: 20
});

Architecture

Notion Client is designed around several key components:

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

Capabilities

Core API Operations

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

class NotionAPI {
  constructor(options?: NotionAPIOptions);
  getPage(pageId: string, options?: GetPageOptions): Promise<ExtendedRecordMap>;
  getPageRaw(pageId: string, options?: GetPageRawOptions): Promise<PageChunk>;
  fetch<T>(options: FetchOptions): Promise<T>;
}

interface NotionAPIOptions {
  apiBaseUrl?: string;
  authToken?: string;
  activeUser?: string;
  userTimeZone?: string;
  kyOptions?: KyOptions;
}

Core API Operations

Collection Operations

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

getCollectionData(
  collectionId: string,
  collectionViewId: string,
  collectionView: any,
  options?: GetCollectionDataOptions
): Promise<CollectionInstance>;

interface GetCollectionDataOptions {
  type?: CollectionViewType;
  limit?: number;
  searchQuery?: string;
  userTimeZone?: string;
  loadContentCover?: boolean;
  kyOptions?: KyOptions;
}

Collection Operations

Search Operations

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

search(params: SearchParams, kyOptions?: KyOptions): Promise<SearchResults>;

interface SearchParams {
  ancestorId: string;
  query: string;
  limit?: number;
  filters?: SearchFilters;
}

Search Operations

Block and User Operations

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

getBlocks(blockIds: string[], kyOptions?: KyOptions): Promise<PageChunk>;
getUsers(userIds: string[], kyOptions?: KyOptions): Promise<RecordValues<User>>;

Block and User Operations

File and URL Operations

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

getSignedFileUrls(
  urls: SignedUrlRequest[],
  kyOptions?: KyOptions
): Promise<SignedUrlResponse>;

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

interface SignedUrlRequest {
  permissionRecord: PermissionRecord;
  url: string;
}

interface SignedUrlResponse {
  signedUrls: string[];
}

File and URL Operations

Types

interface PermissionRecord {
  table: string;
  id: string;
}

interface GetPageOptions {
  concurrency?: number;
  fetchMissingBlocks?: boolean;
  fetchCollections?: boolean;
  signFileUrls?: boolean;
  chunkLimit?: number;
  chunkNumber?: number;
  throwOnCollectionErrors?: boolean;
  collectionReducerLimit?: number;
  fetchRelationPages?: boolean;
  kyOptions?: KyOptions;
}

interface GetPageRawOptions {
  chunkLimit?: number;
  chunkNumber?: number;
  kyOptions?: KyOptions;
}

interface AddSignedUrlsOptions {
  recordMap: ExtendedRecordMap;
  contentBlockIds?: string[];
  kyOptions?: KyOptions;
}

interface FetchOptions {
  endpoint: string;
  body: object;
  kyOptions?: KyOptions;
  headers?: any;
}