kjk/notionapi: Reading Notion Content from Go

Where kjk/notionapi Fits in a Notion Publishing Pipeline

kjk/notionapi addresses a narrow but practical problem for Go programs that need to treat Notion as a content source. The README says it retrieves page content in a structured format, which can then be converted to HTML. That makes the library relevant to static site generators, documentation pipelines, and personal publishing systems that keep editorial content in Notion but publish it elsewhere.

The repository identifies a concrete use case. Its author says a custom Go program downloads Notion pages through this library, converts them to HTML, and publishes the result to Netlify. The same content source is also used for programming books. Based on those examples, the target user is not a general Notion desktop replacement. It is a developer who needs programmatic retrieval and conversion rather than interactive editing.

Most functionality is oriented toward reading. The project describes itself as “Mostly for reading, limited write capabilities.” That distinction matters when planning adoption. A publishing system can use the library as the ingestion layer, but it should not assume that the client can replace every Notion editing workflow. The README does not document a complete list of supported write operations or a formal compatibility contract.

The client is unofficial. The author explains that it was produced by reverse-engineering the Notion API, and the linked article describes that process. This approach may expose useful behavior before or beyond the official API, but it also means interface stability cannot be inferred from the repository alone. The official Notion API is described as being in beta and less capable at the time of the README, but that comparison is contextual rather than a guarantee that this client will remain compatible.

Structured Retrieval and Conversion in kjk/notionapi

The repository layout shows a client centered on authenticated Notion requests and decoding of Notion-specific structures. `client.go` provides the client layer, while files such as `page.go`, `block.go`, `record.go`, and `collection.go` represent the principal content types named by the repository. `inline_block.go` indicates that inline text and block content are handled as distinct parts of the model.

The conversion path is also visible. The top-level `tohtml/` directory points toward HTML generation, while `tomarkdown/` provides a Markdown conversion path. `export_page.go` indicates an export operation at the page level. The README specifically confirms structured retrieval followed by conversion to HTML, so the basic data flow is to retrieve a page, decode its content, and pass that representation into an exporter.

Supporting files suggest more than a simple single-request wrapper. `api_loadCachedPageChunk.go` corresponds to cached page chunk loading, and `caching_client.go` has its own implementation and tests. `submit_transaction.go` corresponds to transaction submission, while `api_syncRecordValues.go` relates to record synchronization. Those names indicate support for cached page data and record-oriented operations, although the README does not provide a sequence diagram or explain synchronization semantics.

Other repository entries cover files, users, comments, discussions, activity, subscription data, email user creation, and signed file URLs. This breadth should not be confused with official Notion API coverage. It describes code that exists in the repository, not a guarantee that every operation is stable or suitable for production automation. The README's central promise remains narrower: retrieve Notion page content in structured form and convert it for publication.

Installation Documentation and the First Go Integration

The README does not provide an installation command, sample client construction, authentication sequence, or runnable first-page export. Its `go.mod` declares the module path `github.com/kjk/notionapi` and requires Go 1.25.5, but a version declaration is not an installation tutorial. This article therefore does not invent `go get` flags, environment variables, credential fields, or client method calls.

The documented starting point is the linked tutorial, “Using Notion API Go client.” The README directs users there for setup guidance and separately links the package documentation at `pkg.go.dev/github.com/kjk/notionapi`. Based on the repository structure, a real first integration would need to create the client, authenticate it, retrieve a page, and pass the result to `tohtml/` or `tomarkdown/`. The README does not show the exact Go calls or expected output for those steps.

That absence is a meaningful adoption constraint. Authentication for an unofficial client is likely to be the first implementation detail a developer must resolve, but the article must not be used as evidence for a particular login flow because the README does not specify one. Likewise, no command or code sample can be copied accurately from the documented pages.

For evaluation, open the linked tutorial and package documentation, then inspect `client.go` and the selected converter. A usable first check should use one known Notion page and determine whether the project retrieves all blocks needed for the intended output. The criterion should be the actual exported document, not merely whether the client initializes.

Unofficial API Status and Content Compatibility Boundaries

The central limitation is the client's unofficial status. It does not wrap a documented, supported Notion API. Its author says it was created by reverse-engineering Notion's API, which means an upstream interface change could break requests or decoding. The README does not define a compatibility policy, supported Notion account tiers, or version matrix.

Content coverage is the second boundary. The library is mainly intended for retrieval and offers limited writes, so applications that create or update complex Notion content are outside its strongest documented use case. The repository includes files for pages, blocks, records, collections, comments, and discussions, but file names alone do not establish complete CRUD support or behavioral parity with the Notion client.

The converters also impose a format boundary. A page can be retrieved successfully while its representation does not map cleanly to HTML or Markdown. Database-like collection structures, inline formatting, tables, files, comments, and other block types can require application-specific rendering decisions. The presence of `simple_table_test.go` shows table-related testing, but it does not prove that every Notion table arrangement is covered.

This is therefore the wrong tool when official support, a stable upstream contract, or complete bidirectional editing is more important than reading flexibility. It is a better fit for a narrowly scoped reader that already accepts maintenance risk and has representative pages for compatibility checks.

Alternatives to kjk/notionapi by Integration Model

The README names a real alternative in another form: the official Notion API. It describes that API as being in beta and not as capable as this unofficial client when the README was written. The practical difference is therefore the source of interface support. kjk/notionapi reverse-engineers Notion behavior and emphasizes structured page reading, while the official API is the official interface, even if its documented capabilities were narrower at that point.

The README also lists implementations for other languages: `jamalex/notion-py` for Python, `petersamokhin/knotion-api` for Kotlin and Java, and `Nishan-Open-Source/Nishan` for node.js and TypeScript. These are alternatives based on language and architecture, not drop-in comparisons with documented feature parity. Their inclusion confirms that reverse-engineered Notion clients exist across ecosystems, but the repository provides no benchmark or support comparison among them.

For a Go project, choosing between libraries with different language bindings is rarely practical. The more relevant decision is between the official Notion API and kjk/notionapi's broader but unofficial reading focus. A team that prioritizes vendor support may accept a smaller feature set. A publisher that already depends on retrieval and conversion of existing Notion content may find kjk/notionapi's approach more aligned with its pipeline, while taking responsibility for compatibility checks.

Maintenance Signals, Release Policy, and BSD-2-Clause Use

The repository is not archived, and the last push was on 2026-09-22. That is recent enough to show current repository activity, but it is not the same as a promise of long-term compatibility with Notion. There are no GitHub releases, so the README and repository provide no release cadence, semantic-version policy, or published migration process to examine.

The upgrade cost is tied to the Go module and upstream API. `go.mod` declares Go 1.25.5 and lists dependencies including `github.com/google/uuid`, `github.com/json-iterator/go`, `github.com/kjk/common`, and `github.com/tidwall/pretty`. A consumer will need to account for those module requirements when integrating the client. The repository also includes `go.work` and `go.sum`, indicating a Go module workspace and locked dependency information in the source tree.

The project uses the BSD-2-Clause license. That identifier permits review under its stated terms, including conditions concerning copyright and redistribution. This is not legal advice, and the LICENSE file should be consulted for the exact obligations. The practical engineering point is narrower: source reuse and distribution should follow that file, while future interface changes may require code changes unrelated to licensing.

Editorial conclusion

Adopt kjk/notionapi when a Go publishing tool needs to read Notion pages into its own structured processing pipeline, and avoid it when a supported API, predictable compatibility, or broad write coverage is a requirement. Before adoption, verify authentication against the linked tutorial, confirm that the page structures required by your exporter are handled, and test the conversion output against representative Notion content.

Frequently asked questions

Official sources

1. Issues
2. kjk/notionapi on GitHub
3. License: BSD-2-Clause
4. Project website
5. README