tashfeenahmed/scallopbot/notion

Typed Notion API

Handles Notion API version 2025-09-03, resolves databases, types property values from the schema, checks HTTP status, and returns compact JSON.

Workflow for a write (one call is usually enough):

1. create with database (a title such as "gym tracker") or a known

database_id/data_source_id, and plain properties. The tool looks the database up in its memory or by search, fetches the schema, and types the values for you. The result includes resolved_from when it resolved a title.

1. Only if the database is unknown: known (remembered databases, free) or

search. Never invent an ID.

1. schema only when a property error asks for it; errors already list the

valid property names and types.

1. Trust completion only when the tool returns success: true with a page_id.

create/update return {page_id, url, title, properties} with flat values. An Unknown database id error means the ID does not exist; it lists the databases the tool knows. It is not a permission problem unless the error says HTTP 401 or 403.

Query responses are compact and date-sorted. For repeated entities, use result.stats_by_title[].latest for the newest dated record and maxima for numeric records. Never infer a personal record, improvement, increase, or trend from an arbitrary row or from response order. Preserve user-supplied titles and labels exactly on writes; do not add modalities such as “Dumbbell” or “each arm”.

Examples:

{"action":"create","database":"gym tracker","properties":{"Name":"Pectoral machine","Date":"2026-08-21","Type":"Machine","Sets":3,"Reps":6,"Weight (kg)":45}}

{"action":"query","database":"gym tracker","filter":{"property":"Date","date":{"equals":"2026-07-13"}}}

{"action":"known"}