Roam Research Docs · Developer documentation

Local API

• Just released, breaking changes might still happen
• The desktop app exposes a local HTTP API on port 3333 for external applications to interact with Roam Alpha API.
• Enable
  • Open the desktop app
  • Open settings menu and enable
    • 
• Port & Last Graph Discovery
  • The port is usually 3333, but if that port is taken we increment until we find a usable port.
  • Read ~/.roam-local-api.json to discover the port and last opened graph:

    • {
        "port": 3333,
        "last-graph": "my-graph-name"
      }

    • port - the current API port (may be stale if app is not running)
    • last-graph - the most recently opened graph name
  • This file persists when the app closes, so check if the port is responsive before using it
• Endpoints
  • Execute API action

    •  text
      POST http://localhost:3333/api/:graph-name
      Content-Type: application/json
      
      {"action": "...", "args": [...]}

    • action - the Roam Alpha API method path (e.g., data.q, data.block.create)
    • args - array of arguments to pass to the method
    • Examples
      • Query all page titles:

        • curl -X POST http://localhost:3333/api/my-graph \
          -H "Content-Type: application/json" \
          -d '{"action": "data.q", "args": ["[:find ?title :where [?e :node/title ?title]]"]}'

      • Create a block:

        • curl -X POST http://localhost:3333/api/my-graph \
          -H "Content-Type: application/json" \
          -d '{"action": "data.block.create", "args": [{"location": {"parent-uid": "abc123", "order": 0}, "block": {"string": "Hello"}}]}'

    • Response
      • Success: {"success": true, "result": [...]}
      • Error: {"success": false, "error": "Local API is disabled. Enable it in Settings menu."}
  • List open graphs

    •  text
      GET http://localhost:3333/api/graphs/open

    • Returns graphs currently open in the desktop app
    • Example

      • curl http://localhost:3333/api/graphs/open

    • Response
      • Success: {"success": true, "result": [{"name": "my-graph", "type": "hosted"}, ...]}
      • type is either "hosted" or "offline"
  • List available graphs

    •  text
      GET http://localhost:3333/api/graphs/available

    • Returns all graphs the user has access to
    • Requires at least one graph window to be open
    • Example

      • curl http://localhost:3333/api/graphs/available

    • Response
      • Success: {"success": true, "result": [...]}
      • Error (no window open): {"success": false, "error": "No graph window open. Please open a graph first."}

markdown version · view in Roam Research · exported 2026-07-03