Roam Research Docs · Developer documentation

roam/agent guidelines

markdown version · view in Roam Research

• This graph is Roam's public developer documentation: the frontend API (Roam Alpha API), Roam Depot/Extension API, the backend/HTTP APIs, roam/js, roam/css, and related pages. Readers are extension developers — human and AI.
• Accuracy is the prime rule
  • These docs describe the Roam codebase. Verify behavioral claims against the source (or by live-testing) before writing them.
  • Implementations outrank code comments and docstrings, which can be stale.
• Style
  • One fact per block; nest details under a short lead block instead of writing long blocks.
  • Code examples show their return values as comments.
  • Don't duplicate content across blocks or pages — link with ((block refs)) or [[page refs]] instead.
• Reading efficiently
  • On Roam Alpha API, every method heading is its full dotted path (roamAlphaAPI.data.block.create) — search that string and fetch just that block instead of loading the whole page.
  • Roam Alpha API (old) is the pre-2026 archive holding the historical change log — don't edit it.