{"id":16482098,"url":"https://github.com/bod/klibnotion","last_synced_at":"2025-07-13T04:36:52.732Z","repository":{"id":45100967,"uuid":"330462851","full_name":"BoD/klibnotion","owner":"BoD","description":"A Notion API client library for Kotlin, Java and more.","archived":false,"fork":false,"pushed_at":"2023-09-17T16:24:45.000Z","size":2718,"stargazers_count":53,"open_issues_count":26,"forks_count":11,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-01T23:45:04.084Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BoD.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-17T18:50:04.000Z","updated_at":"2024-12-04T05:54:12.000Z","dependencies_parsed_at":"2022-09-16T13:46:12.407Z","dependency_job_id":null,"html_url":"https://github.com/BoD/klibnotion","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/BoD/klibnotion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BoD%2Fklibnotion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BoD%2Fklibnotion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BoD%2Fklibnotion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BoD%2Fklibnotion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BoD","download_url":"https://codeload.github.com/BoD/klibnotion/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BoD%2Fklibnotion/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260301994,"owners_count":22988719,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T13:09:37.686Z","updated_at":"2025-06-17T06:04:53.659Z","avatar_url":"https://github.com/BoD.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# klibnotion\n\nA [Notion API](https://developers.notion.com/) client library for Kotlin, Java and more.\n\nThis library is written in [Kotlin Multiplatform](https://kotlinlang.org/docs/reference/multiplatform.html)\nso it can be used from the JVM, Android, iOS, Linux, MacOS, Windows, Javascript and more - in theory. In practice it has\nbeen tested and has samples for the JVM (Kotlin and Java), and MacOS (Kotlin).\n\nSeveral flavors of the client are available to match your needs:\n\n- [Coroutines (`suspend`) based](https://github.com/BoD/klibnotion/blob/master/library/src/commonMain/kotlin/org/jraf/klibnotion/client/NotionClient.kt):\n  the default client for Kotlin projects\n- [Blocking](https://github.com/BoD/klibnotion/blob/master/library/src/commonMain/kotlin/org/jraf/klibnotion/client/blocking/BlockingNotionClient.kt):\n  useful for Java projects, or if you have your own async mechanism\n- [`Future` based (JVM only)](https://github.com/BoD/klibnotion/blob/master/library/src/jvmMain/kotlin/org/jraf/klibnotion/client/future/FutureNotionClient.kt):\n  useful for Java projects\n\n## Usage\n\n### 1/ Add the dependencies to your project\n\n#### Gradle based projects\n\nThe artifact is hosted on the Maven Central repository.\n\n```kotlin\nrepositories {\n    /* ... */\n    mavenCentral()\n}\n```\n\n```kotlin\ndependencies {\n    /* ... */\n    implementation(\"org.jraf:klibnotion:1.12.0\")\n}\n```\n\n### 2/ Use the client\n\nThe easiest way to see how to use it is to look at the samples:\n\n- [Coroutines (Kotlin)](samples/sample-jvm/src/main/kotlin/org/jraf/klibnotion/sample/Sample.kt)\n- [Blocking (Java)](samples/sample-jvm/src/main/java/org/jraf/klibnotion/sample/BlockingSample.java)\n- [Future (Java)](samples/sample-jvm/src/main/java/org/jraf/klibnotion/sample/FutureSample.java)\n\nYou can also explore [the docs](https://bod.github.io/klibnotion/).\n\n#### Get your API key\n\nYou will find your **Internal Integration Token** by following the\ninstructions [here](https://developers.notion.com/docs/authorization).\n\n#### Instantiate a `NotionClient`\n\n```kotlin\nval notionClient = NotionClient.newInstance(\n    ClientConfiguration(\n        Authentication(TOKEN)\n    )\n)\n```\n\nTo get other flavors of the client:\n\n- Blocking: `BlockingNotionClient blockingClient = BlockingNotionClientUtils.asBlockingNotionClient(notionClient)`\n- Future: `FutureNotionClient futureClient = FutureNotionClientUtils.asFutureNotionClient(notionClient)`\n\n#### Use the `NotionClient`\n\nThe client gives access to several API \"areas\":\n\n- [`oAuth`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-o-auth/index.html)\n- [`users`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-users/index.html)\n- [`databases`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-databases/index.html)\n- [`pages`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-pages/index.html)\n- [`blocks`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-blocks/index.html)\n\nEach area exposes related APIs, for\ninstance: [`notionClient.pages.getPage`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-pages/get-page.html)\n.\n\n#### Pagination\n\nThe APIs that are paginated all follow the same principle:\n\n- take\n  a [`Pagination`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.model.pagination/-pagination/index.html)\n  object as a parameter, which defines the page to retrieve\n- return\n  a [`ResultPage\u003cT\u003e`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.model.pagination/-result-page/index.html)\n  with the result list but also a reference to the next `Pagination` objects (handy when retrieving several pages).\n\n#### Content DSL\n\nA small DSL is available on the page creation API, here's an example usage:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n```kotlin\nheading1(\"First section\")\nparagraph(\"Hello, World!\")\n\nheading1(\"Second section\")\nparagraph(\"This paragraph is bold\", annotations = Annotations.BOLD) {\n    paragraph(\"Sub paragraph 1\")\n    paragraph(\"Sub paragraph 2\") {\n        paragraph(\"Sub sub paragraph\") {\n\n        }\n    }\n}\n\nheading2(\"But then again\")\nheading3(\"Actually\")\nparagraph(\"That's the case\")\n\nheading3(\"But really\")\nparagraph(RichTextList().text(\"This \")\n    .text(\"word\", Annotations(color = Color.RED))\n    .text(\" is red\"))\n\nbullet(\"There's this,\")\nbullet(\"there's that,\")\nbullet(\"then there's...\") {\n    paragraph(\"Will this work?\")\n}\nbullet(\"indentation?\") {\n    bullet(\"indentation? 2\") {\n        bullet(\"indentation? 3\")\n    }\n}\n\nnumber(\"First\")\nnumber(\"Second\") {\n    number(\"Second second\")\n}\nnumber(\"Third\")\n\ntoDo(\"This one is checked\", true)\ntoDo(\"This one is not checked\", false)\n\ntoggle(\"This is a toggle!\") {\n    paragraph(\"This first paragraph is inside the toggle\")\n    paragraph(\"This second paragraph is inside the toggle\")\n    heading3(\"This too!\")\n}\n```\n\n\u003c/td\u003e\n\n\u003ctd\u003e\n\u003cimg src=\"assets/content.png\"\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n#### OAuth support\n\n1. Use [`oAuth.getUserPromptUri`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-o-auth/get-user-prompt-uri.html)\n   to get a URI that will prompt users to agree to add your integration to their workspace\n2. After agreeing and upon success, they will be redirected to a specific URI containing a code.\n   Use [`oAuth.extractCodeAndStateFromRedirectUri`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-o-auth/extract-code-and-state-from-redirect-uri.html)\n   to extract the code from this URI.\n3. Exchange the code for an access token\n   using [`oAuth.getAccessToken`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-o-auth/get-access-token.html)\n4. Save this token. You can now use it by setting\n   the [`accessToken`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-authentication/access-token.html)\n   property of\n   the [`Authentication`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-authentication/index.html)\n   object you used when building\n   your [`NotionClient`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/index.html).\n\nSee [the sample](samples/sample-jvm/src/main/kotlin/org/jraf/klibnotion/sample/Sample.kt) for a working example.\n\n#### Logging\n\nTo log HTTP requests/response, pass\na [`HttpConfiguration`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-http-configuration/index.html)\nto [`NotionClient.newInstance()`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-companion/new-instance.html?query=fun%20newInstance(configuration:%20ClientConfiguration):%20NotionClient)\n.\n\nSeveral [levels](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-http-logging-level/index.html)\nare available: `NONE`, `INFO`, `HEADERS`, `BODY` and `ALL`\n\n#### Proxy\n\nA proxy can be configured by passing\na [`HttpConfiguration`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-http-configuration/index.html)\nto [`NotionClient.newInstance()`](https://bod.github.io/klibnotion/klibnotion/org.jraf.klibnotion.client/-notion-client/-companion/new-instance.html?query=fun%20newInstance(configuration:%20ClientConfiguration):%20NotionClient)\n.\n\n## Status\n\n- This library uses the `2021-08-16` version of the Notion API.\n- The Notion API is still evolving and therefore there are some changes that have not been implemented by this\n  library yet.\n- Development on this library is not very active, the main reason being that I am not using the Notion API anymore.\n- However, pull requests are very welcome, and I **will** publish new versions as needed.\n- If you want to contribute, it is recommended you first try an issue with the [\"good first issue\"](https://github.com/BoD/klibnotion/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) label.\n\n## Javascript support\n\nKotlin Multiplatform projects can target Javascript but as of now this library doesn't support it. See [issue #43](https://github.com/BoD/klibnotion/issues/43) if you want to contribute it.\n\n## Author and License\n\n*Note: this project is not officially related to or endorsed by Notion.*\n\n```\nCopyright (C) 2021-present Benoit 'BoD' Lubek (BoD@JRAF.org)\nand contributors (https://github.com/BoD/klibnotion/graphs/contributors)\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbod%2Fklibnotion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbod%2Fklibnotion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbod%2Fklibnotion/lists"}