DamianH.NotionClient 0.1.0

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.

Package	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

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:

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

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