Notion SDK for .Net

A simple and easy to use client for the Notion API

Provides the following packages:

Package	Downloads	Nuget
Notion.Net

Installation

.Net CLI

dotnet add package Notion.Net

Note: default Notion-Version used by NuGet package versions

Package version	Notion-Version
4.0.0-preview-1.8.21.2022	2022-06-28
3.0.0+	2022-02-22
2.0.0+	2021-08-16
1.0.0+	2021-05-13

Usage

Before getting started, you need to create an integration and find the token. You can learn more about authorization here.

Import and initialize the client using the integration token created above.

var client = NotionClientFactory.Create(new ClientOptions
{
    AuthToken = "<Token>"
});

Make A request to any Endpoint. For example you can call below to fetch the paginated list of users.

var usersList = await client.Users.ListAsync();

Dependency Injection

Library also provides extension method to register NotionClient with Microsoft dependency injection.

services.AddNotionClient(options => {
  options.AuthToken = "<Token>";
});

Querying a database

After you initialized your client and got an id of a database, you can query it for any contained pages. You can add filters and sorts to your request. Here is a simple example:

// Date filter for page property called "When"
var dateFilter = new DateFilter("When", onOrAfter: DateTime.Now);

var queryParams = new DatabasesQueryParameters { Filter = dateFilter };
var pages = await client.Databases.QueryAsync(databaseId, queryParams);

Filters constructors contain all possible filter conditions, but you need to choose only condition per filter, all other should be null. So, for example this code would not filter by 2 conditions as one might expect:

var filter = new TextFilter("Name", startsWith: "Mr", contains: "John"); // WRONG FILTER USAGE

To use complex filters, use class CompoundFilter. It allows adding many filters and even nesting compound filters into each other (it works as filter group in Notion interface). Here is an example of filter that would return pages that were due in past month AND either had a certain assignee OR had high urgency:

var selectFilter = new SelectFilter("Urgency", equal: "High");
var assigneeFilter = new PeopleFilter("Assignee", contains: "some-uuid");
var dateFilter = new DateFilter("Due", pastMonth: new Dictionary<string, object>());

var orGroup = new List<Filter> { assigneeFilter, selectFilter };
var complexFiler = new CompoundFilter(
    and: new List<Filter> { dateFilter, new CompoundFilter(or: orGroup) }
);

Supported Endpoints

• Databases
  • Query a database
  • Create a database
  • Update database
  • Retrieve a database
• Pages
  • Retrieve a page
  • Create a page
  • Update page
  • Retrieve page property item
• Blocks
  • Retrieve a block
  • Update a block
  • Retrieve block children
  • Append block children
  • Delete a block
• Comments
  • Retrieve comments
  • Create comment
• Users
  • Retrieve a User
  • List all users
  • Retrieve your token's bot user
• Search

Enable internal logs

The library make use of ILoggerFactory interface exposed by Microsoft.Extensions.Logging. Which allow you to have ability to enable the internal logs when developing application to get additional information.

To enable logging you need to add the below code at startup of the application.

// pass the ILoggerFactory instance
NotionClientLogging.ConfigureLogger(logger);

You can set the LogLevel in config file.

{
  "Logging": {
    "LogLevel": {
      "Notion.Client": "Trace"
    }
  }
}

You can also refer examples/list-users example.

Contributors

This project exists thanks to all the people who contribute.

Contribution Guideline

Hello! Thank you for choosing to help contribute to this open source library. There are many ways you can contribute and help is always welcome. You can read the detailed Contribution Guideline defined here - we will continue to improve it.