diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cf9272d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,37 @@
+# notion-database
+
+Fetch pages (entries) from database and map/transform the pages to a type.
+
+## Notion
+
+### Notion key
+
+How to obtain new API key and connect it to database/page/etc.:
+
+1. Go to [`https://www.notion.so/profile/integrations`](https://www.notion.so/profile/integrations)
+1. Click 'New integration'
+1. Name the integration
+1. Select workspace and type
+1. Save new integration
+1. Continue to integration settings
+1. Copy the key and keep it safe!
+1. Modify capabilities as needed
+1. Go to your workspace to the page/database
+1. Click the three dots (top right corner) and select connections
+1. Add your new integration to grant access to the page/database to the integration
+
+### Database ID
+
+Go to Notion GUI on web, to the database, copy the hash/ID.
+
+Example:
+
+The URL is `https://www.notion.so/mareshq/1eb611d502b1807bbc5df523a3acc322?v=1eb611d502b180218d5b000c62cd80a8`, the database ID is `1eb611d502b1807bbc5df523a3acc322` and its located in the path, the segment after `/mareshq/<database-id>`. Aka `https://www.notion.so/<workspace-slug>/<database-id>`.
+
+## Working with the Notion SDK (`@notionhq/client`)
+
+The JavaScript SDK is only a simple wrapper on top of Notion's HTTP API, therefore only generic types are available and I find it tricky to work with types.
+
+Instead of trying to figure out the types with the type definition, go to the API documentation (see [Notion Developer portal](https://developers.notion.com/))and work with the schema from there. It was much easier.
+
+Also type casting response pages is tricky, just do mapping. But you will have to do a lot of `null` checks, without them you will pray that everything works. Until it breaks. This proof-of-concept does not check for `null`, but you should!