This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle
What I Built
A person writes one sentence. Hearth designs the pages, databases, properties, and views, shows the result before anything is written, then builds the parts the public Notion API can create. Whatever the API cannot do is returned as a short companion: exact clicks, in order, on the right page.
The problem
Notion is generous and easy to get lost in. A new workspace starts as a blank page. The useful structure — a home page, a database per kind of work, a status, a due date, a board, a calendar, a relation between them — takes a long time to assemble, and most people stop halfway. They end up with one table and a dozen loose notes.
Templates exist, but a template is someone else’s life. A student, a studio, and a household do not want the same columns. They want the shape of their sentence.
The missing step is the one in between: turn a description into a design, let the person look at it, then create only what Notion will actually accept.
Who it is for
Anyone who can describe the room they need and has a Notion account. The first version is aimed at a single person on a free workspace: a student setting up a term, a researcher setting up a desk, a small studio setting up clients and a calendar. It is not a team installer and it does not ask for an admin.
What I built
Hearth is a web app with four moves.
- Write a brief. One box. A sentence or two is enough. Mood and job can sit in the same line.
- Read the preview. A sidebar of rooms, the page as it will read, the database as a board or a calendar, the colours, and a split between “this will be created” and “this stays by hand.”
- Rehearse. The same builder runs against an in-memory Notion. Nothing in the real workspace changes. The log shows every page, view, and relation that would be sent.
- Create. A personal access token builds the workspace as that person. The token is used for the build and then forgotten. It is not stored.
There is also a catalogue. Each row says one of three things: Notion offers this, Hearth creates this, or the person still does it by hand. Every row links to the official page it came from.
One example, all the way through
This is the brief I kept on the desk while building:
Aesthetic + warm + rich. A student dashboard for assignments, revision and projects.
Hearth reads three decisions in that line.
- The mood is warm and rich, so the palette is clay, cream, olive, and ink, and the workspace is named The Study.
- The job is a student dashboard, so the hub is Courses.
- The nouns are assignments, revision, and projects, so those become the other three databases.
The preview then shows a small house, not a pile of features.
| Room | What it is |
|---|---|
| The Study | The front page. A short introduction, the list of rooms, and the colour note. |
| This week | Only what is due in the next seven days, plus live views of the databases. |
| Courses | The term, named. Other databases point here. |
| Assignments | A status, a due date, a type, an estimate in hours, and a course. |
| Revision | A topic, a confidence, a method, and the next review date. |
| Projects | Longer work, with the outcome written in one sentence. |
| How this space works | What was created, and the clicks that are still yours. |
Assignments opens on a board grouped by status, and also has a calendar on Due. Starter rows are real enough to judge the design: Mechanism worksheet belongs to Organic Chemistry, and that link is a relation, not a name typed into a text field. Three rows per database. Enough to see the board. Few enough to delete.
The companion does not say “set up automations.” It says: open Assignments, add one automation, trigger it when Status becomes Done, and write today’s date into Completed. Same tone for the cover, the reminder on Due, and the template for a new assignment.
How it works
The pipeline is five steps. Each one can fail without taking the others down.
1. Design.
With no model key, an atelier reads the brief. It picks a domain (student, research, studio, household, product, writing, or personal), a mood, and the databases named in the sentence. If the sentence names nothing, the domain supplies a small default set. Relations are added only when both sides exist. A board is grouped only by a status or a select. A calendar is bound only to a date.
If a Gemma key is set, Gemma drafts the same kind of plan. The draft is repaired before it can reach Notion: unknown property types are dropped, a board without a group is dropped, a relation to a missing database is dropped. If the repair leaves nothing usable, the atelier plan is kept and the preview says so.
2. Consult the docs.
Before the preview is shown, Hearth fetches the official pages it is about to rely on: creating a page, creating a database, data source properties, working with views, and personal access tokens. The index those pages come from is Notion’s public llms.txt. If a fetch fails, the link and the reason are still shown. The build does not invent a capability because a page was offline.
3. Validate.
Every property and every view is checked against a catalogue. The catalogue is the contract. “Notion supports charts” and “this build will create a chart” are different sentences. Charts, maps, buttons, and formulas are left as manual steps, because a bad formula can fail an entire database, and a chart depends on the workspace plan.
4. Preview.
The person walks the rooms. Switching a database from Board to Calendar uses the starter rows, so October shows the worksheet on the day it is due. Nothing has been written to Notion yet.
5. Build.
The builder speaks Notion API version 2026-03-11. The order matters.
- Create the home page, then the other pages.
- Create each database with its first data source and its default table.
- Add relations only after both data source ids exist.
- Rename the default table, then add the board, calendar, list, gallery, timeline, and filtered tables.
- Place linked views of those databases on This week.
- Add starter rows in dependency order, so a course exists before an assignment points at it.
- Append the companion to How this space works.
A step that Notion refuses is recorded, skipped, and rewritten as a manual step. The rest of the workspace still gets created.
What I used, and what I refused to pretend
Notion publishes enough to build this without private source code.
| Source | What I took from it |
|---|---|
| Help Center | What pages, databases, views, templates, and automations mean to a person. |
| Developer docs | The request shapes: pages, data sources, properties, views, filters, parents. |
llms.txt |
The map of those docs, so the app can fetch the page it needs instead of guessing. |
| The API | The actual create calls. Available on every plan, including Free, with a personal access token. |
| Notion MCP | Proof that an assistant can create pages, databases, and views. Hearth does not require MCP. The REST API is enough for a free workspace, and some MCP tools are limited to paid plans with Notion AI. |
I kept a hard line between three facts.
- Notion offers it. Boards, calendars, galleries, relations, templates, automations, charts.
- Hearth creates it. Pages, icons, text and status and date and number and checkbox properties, relations, the views above, linked views, and starter rows.
- The person still does it. The cover image, a database template, a date reminder, one automation, and sharing. Buttons are ignored if you send them in a schema write. Charts can be created by the API, but the configuration depends on the plan, so this version does not guess it.
That line is the part I would want a judge to notice. A builder that claims every Notion feature is a builder that fails on the third call.
Decisions I would defend
Preview before write.
The costly mistake is a wrong database in someone’s real sidebar. Rehearsal and the preview exist so the person can say no.
A catalogue, not a one-time reading of the docs.
Reading the documentation once would go stale. The catalogue is checked on every plan. The live docs are consulted for the pages the plan actually uses. When Notion changes a request, one of those two will show it.
Repair the model, do not trust it.
Gemma is optional. The atelier already produces a plan the builder can execute. The model is allowed to change names, rooms, and copy. It is not allowed to invent a property type the API will reject. If it does, that part is removed and named.
A personal access token, not a stored login.
On the Free plan, the workspace owner can create a token and the API will create a private page as them. An internal integration is the other door: it only sees pages shared with it, so the person picks the parent. The token stays in the browser tab for the build. The server does not write it down.
Small on purpose.
A handful of pages, the databases the sentence asked for, three starter rows each. Free workspaces have a block limit. A first version that creates fifty databases is not a kindness.
What went wrong, and what I changed
The first token build failed in a way the happy path did not show.
Notion returns a personal access token as a bot user. I treated every bot as an internal integration and tried to build inside the page the person had edited most recently. That is the wrong parent. A token that belongs to a person is allowed to create a private page at the top of the sidebar. An internal integration is not. The check now tells those two apart.
The page body also used an icon the current API rejects, so the first create died before any database existed. Page writes now use the documented emoji form, and if the block body is refused, the same page is sent again as markdown. When Notion refuses a call, the status and the message are printed in the server log. Before that, the failure lived only inside the response, which made it look like nothing had happened.
What I am not claiming
- Hearth does not read Notion’s private source.
- It does not turn on automations, upload a cover, or invite a teammate.
- Gemma is not required. With no key, the atelier designs the workspace.
- A free API does not mean a free model or free hosting. Those are separate costs.
- Some MCP tools, and charts, depend on the workspace plan. The first version stays on the calls a free workspace can make.
What I would do next
Keep the catalogue honest as Notion’s API moves. The next useful step is applying a database template once the person has created one, because the API can apply a template and still cannot design it. After that, a public connection so a teammate can authorize Hearth without pasting a token.
The product, as it stands, is the sentence I started with.
Describe the workspace. Look at the rooms. Create the ones Notion will accept. Leave the rest as instructions a person can follow without guessing.
Top comments (0)