# notionapi: a Go client for the Notion API, one file per resource

> notionapi is a Golang implementation of a client for the Notion API, covering all endpoints of the 2022-06-28 API version, with the repository laid out so that each Notion resource, blocks, databases, pages, properties, search, users, comments and filters has its own file alongside its test file.

**jomei/notionapi** — A Notion API SDK, written in Golang

- Repository: https://github.com/jomei/notionapi
- Website: https://pkg.go.dev/github.com/jomei/notionapi
- Stars: 572 · Forks: 85
- Language: Go
- License: BSD-2-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/jomei-notionapi

## A typed Go client, not a generic HTTP wrapper

The project describes itself as a Golang implementation of an API client for the Notion API, and the documentation site for it is on pkg.go.dev rather than a separate docs site, which is the norm for a Go library. The scope is stated precisely: it supports all APIs of the Notion API version 2022-06-28. That single sentence is the most important line in the README for an adopter, because Notion has added endpoints since then and this client does not claim to cover them. The audience is Go developers who want to talk to a Notion workspace from a service, a script or a bot, and who would rather have request and response types in Go than assemble JSON bodies by hand. The licence is BSD-2-Clause, the module is github.com/jomei/notionapi, and the last push to the repository was on 2026-08-07.

## Installing it and getting a token

The package is a standard Go module, so installation is a single fetch.

```bash
go get github.com/jomei/notionapi
```

Before any of that, you need credentials, and the README points you at the Notion Getting Started Guide to obtain an integration token. The client is then created by importing the package and passing that token to the constructor.

```go
import "github.com/jomei/notionapi"

client := notionapi.NewClient("your_integration_token")
```

That is the whole setup. There is no separate configuration struct, no endpoint override for self-hosted proxies, and no retry or rate limit policy visible in the README, which tells you this is a thin typed wrapper and that anything more elaborate is something you build on top of it. The go.mod file is minimal, with a module path and a go directive of 1.14 and no require block at all, so the library itself pulls in no third party dependencies. That is worth noting for anyone with a strict dependency policy, because a Notion client that depends on nothing beyond the standard library is unusual and convenient.

## Calling the API through per-resource services

The client exposes groups of methods per Notion resource, and the example in the README retrieves a page through the Page service with a context and a page id.

```go
page, err := client.Page.Get(context.Background(), "your_page_id")
if err != nil {
    // Handle the error
}
```

The repository layout shows the full set of services, and it is a good map of the Notion API surface. There are files for authentication, blocks, comments, data sources, databases, pages, properties, property configuration, search, sort, users, objects, filters and the downloadable interface, plus client.go for the client itself, const.go for constants, error.go for error handling, and object.go for the shared object model. Several of these have a matching test file, and the naming is consistent enough that the structure alone tells you the library is organised around Notion's own object model rather than around a generic REST abstraction. The data_source.go and property_config.go files are the newer parts of the Notion model, which is a hint about how the library has kept pace with the platform's own schema changes.

## Blocks, filters and the query surface

Three parts of the layout deserve a closer look because they are where a Notion client earns its keep. The block model is the interesting one, because Notion's page content is a tree of typed blocks, and a client that models those blocks as Go values saves you a lot of interface switch statements. The filter and sort files correspond to Notion's query parameters, which is the difference between fetching a database's rows and asking a database for the rows that match a condition, and between asking for them in an order that matters. The property and property_config files cover the type system Notion uses for database columns, which is a wide and occasionally awkward surface: title, rich text, number, select, multi select, date, people, files, checkbox, url, email, phone number, relation, rollup and formula all have different shapes, and each of those is a Go type here. The downloadable interface file suggests the library also exposes a way to fetch exported content rather than only live pages.

## Where notionapi is the wrong choice

The obvious limit is the version boundary. The client supports the Notion API version 2022-06-28, and Notion has added endpoints since, so a feature you need that was introduced later is simply not there and you would have to drop down to raw HTTP for that call and give up the types. The second limit is the thinness. With no dependencies, no retry logic and no rate limit handling in the visible surface, a client used from a long running service has to cope with Notion's own request limits itself, and a client used from a flaky network has to implement its own backoff. The third is the Go-only constraint, which is obvious but worth stating since Notion's community integration scripts are usually Python or JavaScript, so this library is for a team that has already committed to Go. The alternative worth naming is the official Notion SDK, which is maintained alongside the platform and therefore tracks new endpoints, and the difference in approach is exactly the version pinning versus version tracking choice. If your work is a script that touches a workspace occasionally, the official SDK is the lower-risk option; if it is a Go service with a stable set of endpoints, this library is a good fit.

## Maintenance, testing and the shape of the project

The release history shows a steady cadence with a long tail of patch releases: v1.13.1 in June 2024, v1.13.2 in September 2024 and v1.13.3 in December 2024, and the last push to the repository was on 2026-08-07. The project is not archived, so it is still receiving changes, but the newest tag is almost two years older than the last commit, which usually means bug fixes are landing on main without a release being cut. The README carries a test badge pointing at a test workflow, and the repository layout has a test file beside every source file, with a testdata/ directory for fixtures, so the project is structured for the standard Go table-driven test style. There is also an http/ directory for the transport layer and a pkg/ directory whose contents the README does not describe. The topics are minimal, just go, golang, notion and notion-api, which is an accurate signal of the project's size and focus.

## Conclusion

Adopt notionapi if you are writing a Go service that reads or writes Notion and want a typed client rather than hand-rolled HTTP calls, and if you are content with a client pinned to the 2022-06-28 API version. Do not adopt it if you need endpoints added to Notion after that version, since the README states the support boundary as that version. Verify first which Notion API version your integration is on, and check the last release date, because the newest tag is v1.13.3 from 2024-12-20 while the repository was pushed to more recently.

## FAQ

### Which version of the Notion API does notionapi support?

The README states that it supports all APIs of the Notion API version 2022-06-28. Endpoints added to Notion after that date are not covered.

### How do I install and initialise the notionapi Go client?

Run go get github.com/jomei/notionapi, obtain an integration token following the Notion Getting Started Guide, then import the package and pass the token to notionapi.NewClient. The module declares a go directive of 1.14 and lists no third party dependencies.

### How does the notionapi client organise the Notion API?

By resource, with separate files for authentication, blocks, comments, data sources, databases, pages, properties, property configuration, search, sort, users, objects, filters and the downloadable interface, plus client.go, const.go and error.go. Each area has a matching test file and there is a testdata directory for fixtures.

### When was the last notionapi release and what licence does it use?

The most recent tag is v1.13.3 published on 2024-12-20, after v1.13.2 in September 2024 and v1.13.1 in June 2024, and the repository was last pushed to on 2026-08-07. The licence is BSD-2-Clause.

## Sources

- [jomei/notionapi on GitHub](https://github.com/jomei/notionapi)
- [License: BSD-2-Clause](https://github.com/jomei/notionapi/blob/main/LICENSE)
- [Project website](https://pkg.go.dev/github.com/jomei/notionapi)
- [README](https://github.com/jomei/notionapi/blob/main/README.md)
- [Releases](https://github.com/jomei/notionapi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jomei-notionapi