Roadmap: remaining Notion API gaps (post-v0.7.0)

[4ier]

Status — v0.7.0 shipped 🎉

Tier 1 + Tier 2 work done in v0.7.0 (see release notes). Remaining:

• Migrate 'db' surface to the 2025-09-03 data_sources API #39 Data Sources migration — Notion 2025-09-03 breaking API change; planned for next major.
• Expose the /v1/views API (parked — build on demand) #40 Views API — still parked; build on demand.

---

Goal

Track the remaining gaps between Notion's REST API (as of the 2025-09-03 OpenAPI spec) and the CLI's command surface, now that v0.7.0 has shipped Tier 1 + Tier 2 (closes #33–#38).

Maintainer-facing meta issue — individual work items have their own issues linked below.

Background

Notion REST API: ~37 endpoints across blocks, pages, databases, data sources, comments, file uploads, users, search, views, custom emojis, OAuth.
CLI in v0.7.0: ~24 endpoints covered.

Full audit: see the discussion under #26 / v0.6.0 release. Short version:

Area	Covered	Gap
Blocks	5/5	—
Pages	7/7	— ✓
Databases (old)	4/4	— (but being superseded)
Data Sources (new)	0/5	entire new resource
Comments	5/5	— ✓
File Uploads	4/5	complete (multi-part)
Users	3/3	—
Search	1/1	—
Views (new)	0/8	entire new resource
Custom Emojis (new)	0/1	—
OAuth	0/3	intentionally out of scope (see DESIGN.md)

Tier 1 — small, high ROI (unblock agent workflows, <100 LoC each)

• comment update / comment delete: expose the two new 2025 API endpoints #33 — comment update / comment delete
• file get <upload-id>: retrieve a single file upload by id #34 — file get <upload-id>
• page archive / page trash: clearer aliases for the soft-delete command #35 — page archive / page trash alias (naming fix)
• block update --file: support markdown updates like append/insert #36 — block update --file for markdown-aware edits

Tier 2 — medium, high user impact

• page markdown / page set-markdown: first-class wrappers around the new markdown endpoints #37 — page markdown (read) and page set-markdown (replace)
• page property: fix silent truncation of relation / rollup values (>25 items) #38 — page property for paginated relation / rollup values

Tier 3 — tracking / upstream churn

• Migrate 'db' surface to the 2025-09-03 data_sources API #39 — Data Sources migration (API version bump, new db datasource subcommands)
• Expose the /v1/views API (parked — build on demand) #40 — Views API (parked; build on demand)
• Custom Emojis (single endpoint; folded into this meta issue, no separate tracking issue needed)

Not planned

• OAuth flow / public integration auth. Explicitly ruled out in DESIGN.md — the CLI targets internal integrations. Re-open only if the scope changes.
• Webhooks. Not a REST concern; out of scope for a CLI.

How to use this issue

• Each non-trivial item has its own issue with full spec (see links above once created).
• Closing a linked issue via a PR that uses Closes #NN ticks it off here automatically.
• When this checklist hits zero uncovered gaps worth closing, close the meta issue and archive the tracking label.