Notion SDK for .NET

A .NET 10 client library and CLI tool for the Notion API (API version 2025-09-03), ported from the official notion-sdk-js v5.9.0.

Packages

Package	Description	NuGet	Downloads
DamianH.NotionClient	.NET client library for the Notion API
DamianH.NotionCli	.NET CLI tool for the Notion API

Table of Contents

NotionClient

• Features
• Installation
• Quick Start
  • Dependency Injection (recommended)
  • Standalone
• Endpoint Groups
• Pagination

NotionCli

• Overview
• Installation
• Authentication
• Usage Examples
• Command Reference

General

• Contributing
• License

---

Features

Package: DamianH.NotionClient — A .NET client library for the Notion API with full coverage of all endpoints.

• 30 API endpoints across 9 endpoint groups (Blocks, Databases, Pages, Users, Comments, Search, FileUploads, DataSources, OAuth)
• AOT-compatible and trimmable — source-generated System.Text.Json serialization with zero reflection
• IAsyncEnumerable<T> pagination helpers — iterate or collect all pages with a single call
• IHttpClientFactory / DI integration via services.AddNotionClient(...)
• Strongly-typed models with polymorphic deserialization

Installation

dotnet add package DamianH.NotionClient

Quick Start

Dependency Injection (recommended)

services
    .AddNotionClient()
    .ConfigureHttpClient(c =>
    {
        c.BaseAddress = new Uri("https://api.notion.com/v1/");
        c.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", configuration["Notion:Token"]);
    });

Resolve INotionClient from the container and use it:

var page = await notionClient.Pages.Get("page-id");

Standalone

var httpClient = new HttpClient
{
    BaseAddress = new Uri("https://api.notion.com/v1/")
};
httpClient.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "secret_...");
httpClient.DefaultRequestHeaders.Add("Notion-Version", "2025-09-03");

var client = new NotionClient(httpClient);
var page = await client.Pages.Get("page-id");

Endpoint Groups

Group	Interface	Description
Blocks	IBlocksClient	Retrieve, append, update, and delete blocks
Databases	IDatabasesClient	Create, query, retrieve, and update databases
Pages	IPagesClient	Create, retrieve, update pages and page properties
Users	IUsersClient	List and retrieve users, get bot user
Comments	ICommentsClient	Create and list comments
Search	ISearchClient	Search pages and databases by title
FileUploads	IFileUploadsClient	Upload and manage files
DataSources	IDataSourcesClient	Query and manage data sources
OAuth	IOAuthClient	Token exchange, revocation, and introspection

Pagination

Use PaginationHelpers to iterate all pages of a paginated endpoint:

await foreach (var block in PaginationHelpers.Enumerate(
    (cursor, ct) => client.Blocks.ListChildren("block-id",
        new PaginationParameters { StartCursor = cursor }, ct)))
{
    // process each block
}

Or collect everything into a single list:

IReadOnlyList<User> allUsers = await PaginationHelpers.CollectAll(
    (cursor, ct) => client.Users.List(
        new PaginationParameters { StartCursor = cursor }, ct));

---

Notion CLI

Package: DamianH.NotionCli — A .NET CLI tool providing full access to all Notion API endpoints from the command line.

CLI Installation

Install as a global .NET tool:

dotnet tool install -g DamianH.NotionCli

Or install locally (available within the current directory tree):

dotnet tool install DamianH.NotionCli

Verify installation:

notion --help

Authentication

The CLI resolves an API token using the following priority order:

Priority	Source	Details
1 (highest)	--token option	Pass directly on the command line
2	NOTION_TOKEN env var	Set in your shell or CI environment
3 (lowest)	~/.notion/config.json	Persistent local config file ({"token": "secret_..."})

Usage Examples

Query a database:

notion databases query --id "database-id"

Get a page:

notion pages get --id "page-id"

Search by title:

notion search --json '{"query": "Meeting Notes"}'

List all users (auto-paginate):

notion users list --all

Create a database from a file:

notion databases create --json @request.json

Command Reference

Command	Description	Reference
blocks	Operations on Notion blocks	docs
databases	Operations on Notion databases	docs
pages	Operations on Notion pages	docs
users	Operations on Notion users	docs
comments	Operations on Notion comments	docs
search	Search pages and databases by title	docs
file-uploads	Upload and manage files	docs
data-sources	Operations on Notion data sources	docs
oauth	Notion OAuth 2.0 token management	docs

For the full CLI reference including pagination, JSON input patterns, error handling, and global options, see docs/cli/README.md.

---

Contributing

Bug reports should be accompanied by a reproducible test case in a pull request.

License

MIT