Notion Seed

notion-seed

Load rows from a JSON file into a Notion database. Supports all common property types: select, multi_select, checkbox, date, number, rich_text, title, url, email, phone_number, relation.

Includes a relation rewiring pass: when seeding self-relating data (e.g. Tasks with Dependencies), use a Template Group text property as a stable ID, store dependencies as comma-separated group IDs in another text property, and then call rewire_relations_by_group to map group IDs to real page IDs.

Prerequisites

• NOTION_API_KEY env var
• Target DB ID
• A JSON seed file (see format below)

Seed JSON format

[
  {
    "title": "Site measurement and as-built drawings",
    "properties": {
      "Task Category": {"select": "Design Iteration"},
      "Project Stage": {"select": "Client Consultation and Pre-Planning"},
      "Applicable Scopes": {"multi_select": ["Full Home Interior", "Modular Kitchen"]},
      "Is Template": {"checkbox": true},
      "Template Group": {"rich_text": "design-01"},
      "Depends On Groups": {"rich_text": "boq-01"}
    }
  }
]

Steps

1. Confirm the target DB ID and title property name (often "Name", "Item Name", "Task Action", etc.).
2. Always check schema first — invoke notion-schema-dump if SCHEMA-REFERENCE.md is missing or stale. Verify every property name in the seed file matches the live DB exactly (case-sensitive).
3. Run:

   from notion_os_toolkit import auth, client, seeder
   nc = client.NotionClient(auth.load_token())
   created = seeder.seed_from_json(nc, "<db_id>", "<title_prop>", "seeds/things.json")
   

4. If the seed file uses Template Group + Depends On Groups for self-relations, second pass:

   seeder.rewire_relations_by_group(
       nc, created,
       group_property="Template Group",
       depends_property="Depends On Groups",
       relation_property="Dependencies",
   )
   

5. Report count seeded and count rewired.

Input/Output contract

Input: seed JSON path, target DB ID, title property name Output: list of created page IDs; on rewire pass, count of rows updated

When NOT to use

• For < 5 rows, just use the Notion UI directly.
• For relations to a DIFFERENT DB (not self), set the relation property directly in the seed file with the target page IDs.

Schema-first reminder

If a property name in your seed file doesn't match the live DB exactly, the API returns 400 and the row is rejected. Always check SCHEMA-REFERENCE.md (regenerate via notion-schema-dump) before running this skill.