Notion API

The Notion API SDK for .NET provides access to the Notion API REST APIs from .NET applications.

Tip

Looking for a specific signature, model, enum, or error type? This SDK ships a generated, machine-readable SDK map — a lookup index of the SDK's entire C# surface. Consult it before grepping or scanning the source tree; it answers most contract questions directly and, when a source file is genuinely needed, names the exact one to open. Details under SDK map.

The Notion API allows developers to integrate with Notion workspaces programmatically. Build integrations that connect Notion with other tools, automate workflows, and manage workspace content including pages, databases, blocks, users, comments, and search. Notion is an all-in-one workspace that combines notes, tasks, wikis, and databases into a flexible, collaborative platform.

---

Installation

Add the .NET SDK as a project reference into your solution:

dotnet add reference <path-to-sdk>/NotionApi.csproj

---

Quick Start

Dependency Injection

Register the client with IServiceCollection and resolve it from the container. The HttpClient is managed by IHttpClientFactory. Configure the client's behavior through NotionApiClientOptions.

services.AddNotionApiClient(options =>
    {
        options.BearerAuth = "YOUR_BEARER_TOKEN";
        options.Environment = ServerEnvironment.Production;
        // TODO: configure more client options here
    });

Direct Instantiation

Create the client by passing an HttpClient you manage yourself. Configure the client's behavior through NotionApiClientOptions.

var httpClient = new HttpClient();
// TODO: configure more client options here
var options =
    new NotionApiClientOptions
    {
        BearerAuth = "YOUR_BEARER_TOKEN",
        Environment = ServerEnvironment.Production,
    };
var client = new NotionApiClient(httpClient, options);

---

Usage

For code examples and error responses, see API Reference.

SDK map

This SDK ships a generated SDK map — sdk-map.md plus the map/ pages — a deterministic, lookup-oriented table of contents of the SDK's C# surface, generated by APIMatic alongside this SDK.

Read it before scanning the source. Whether you are an AI coding assistant or searching by hand, the map answers "what is the exact …" by lookup for every call-level contract, and for anything it does not carry it names the one file that does — so you never have to search the source tree:

• sdk-map.md — the index: client construction, servers/auth, the options/retry reference, the SDK-wide defaults the operation rows rely on, and link tables into map/.
• map/operations/ — one page per controller: the exact C# signature, the return type, the error type with its typed TryGet… accessors, and pagination — plus, per operation, a Type sources table naming the file that declares every type that operation mentions.

Model shapes — record fields with their JSON wire names, enum member names and wire values, OneOf/AnyOf union variants — are not duplicated in the map. Take the path from the operation's Type sources table and read the declaring file; it is the single source of truth and cannot go stale against the code.

Each operation row states what is specific to that operation. The SDK-wide defaults are stated once in sdk-map.md — throw-only (no Result-style no-throw variants), no pagination, the four fixed RawError accessors, the Default server group — and a row appears only where its operation departs from one. A row silent on pagination is telling you that operation has none.

The HTTP verb and route, and the endpoint's behavioural prose, live on the operation itself, in the source file named at the top of its operations page. Read them there when something needs them — wiring a mock, reading a provider log, or settling a rule about what you must pass.

Workflow: look the fact up in the map → where the map leaves something ambiguous, open the one source file the row names → the compiler is the backstop (a name that isn't in the map won't build). Don't scan or grep the tree to find things — the map is the locator.

Which one to reach for

The map and the API Reference answer different questions, and the map is generated from this SDK's source so it stays in lockstep with the code it describes.

Use	For
sdk-map.md + map/	Traversing the SDK and working out its surface — locating the operation you need (this SDK exposes 5 operations), its exact signature and parameter order, the shape and JSON wire names of the models it takes and returns, which error type it throws and how to read it, and the source file behind any of it. This is the index to consume the SDK from, and the one to reach for first.
api-reference.md	Usage guidance for a single operation once you know which one you want — a runnable code sample, per-parameter descriptions, and the error responses it can return.

Best Practices

Tip

Use a single NotionApiClient instance for the lifetime of your application and reuse it across all requests. Creating a new instance per request might exhaust the connection pool.

License

This SDK is distributed under the MIT License.

---

Support

Refer to the API reference for detailed information on available operations with code samples.

For further assistance, please contact support at developers@makenotion.com.

---