ClientOptions

The ClientOptions interface defines all configuration options that can be passed to the Client constructor.

Type Definition

type ClientOptions = {
  auth?: string
  timeoutMs?: number
  baseUrl?: string
  logLevel?: LogLevel
  logger?: Logger
  notionVersion?: string
  fetch?: SupportedFetch
  agent?: Agent
  retry?: RetryOptions | false
}

Properties

string

The Notion API token or OAuth access token for authentication.Default: undefined (must be provided per-request or set on the client)

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
})

LogLevel

The minimum log level for console output. Use LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, or LogLevel.ERROR.Default: LogLevel.WARN

import { Client, LogLevel } from "@notionhq/client"

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  logLevel: LogLevel.DEBUG,
})

number

Request timeout in milliseconds.Default: 60000 (60 seconds)

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  timeoutMs: 30000, // 30 seconds
})

string

The base URL for the Notion API. Useful for testing or proxying requests.Default: "https://api.notion.com"

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  baseUrl: "https://api-proxy.example.com",
})

Logger

Custom logger function that receives log level, message, and extra information.Default: makeConsoleLogger("@notionhq/client")Type signature:

type Logger = (
  level: LogLevel,
  message: string,
  extraInfo: Record<string, unknown>
) => void

Example:

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  logger: (level, message, extraInfo) => {
    console.log(`[${level}] ${message}`, extraInfo)
  },
})

string

The Notion API version to use. This sets the Notion-Version header.Default: "2025-09-03" (from Client.defaultNotionVersion)

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  notionVersion: "2025-09-03",
})

SupportedFetch

Custom fetch implementation. Useful for testing or using alternative fetch libraries.Default: fetch (global fetch)Type signature:

type SupportedFetch = (
  url: string,
  init?: SupportedRequestInit
) => Promise<SupportedResponse>

Example:

import nodeFetch from "node-fetch"

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  fetch: nodeFetch as any,
})

Agent

HTTP agent for Node.js requests. Silently ignored in browser environments.Default: undefinedType: import("node:http").AgentExample:

import { Agent } from "node:http"

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  agent: new Agent({ keepAlive: true }),
})

RetryOptions | false

Configuration for automatic retries on rate limit (429) and server errors. Set to false to disable retries entirely.Default: { maxRetries: 2, initialRetryDelayMs: 1000, maxRetryDelayMs: 60000 }RetryOptions type:

type RetryOptions = {
  maxRetries?: number           // Default: 2
  initialRetryDelayMs?: number  // Default: 1000
  maxRetryDelayMs?: number      // Default: 60000
}

Retry behavior:

Rate limits (429) are always retried for all HTTP methods
Server errors (500, 503) are only retried for idempotent methods (GET, DELETE)
Uses retry-after header when present, otherwise exponential back-off with jitter

Example - custom retry settings:

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  retry: {
    maxRetries: 3,
    initialRetryDelayMs: 2000,
    maxRetryDelayMs: 30000,
  },
})

Example - disable retries:

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
  retry: false,
})

LogLevel

enum LogLevel {
  DEBUG = "debug",
  INFO = "info",
  WARN = "warn",
  ERROR = "error",
}

RetryOptions

type RetryOptions = {
  maxRetries?: number           // Default: 2
  initialRetryDelayMs?: number  // Default: 1000
  maxRetryDelayMs?: number      // Default: 60000
}

Client

Blocks

Pages

Databases

Data Sources

Users

Comments

File Uploads

Search & OAuth

Helpers

Errors

Type Definition

Properties

LogLevel

RetryOptions

See Also

​Type Definition

​Properties

​Related Types

​LogLevel

​RetryOptions

​See Also

Type Definition

Properties

Related Types

LogLevel

RetryOptions

See Also